[docs] comma after leading optional argument is after bracket in docs (issue 15831)

[chris.jerdonek at gmail.com]

Reviewers: ezio.melotti,

Message:
Responding to Ezio's two comments.


http://bugs.python.org/review/15831/diff/5943/Doc/library/functions.rst
File Doc/library/functions.rst (right):

http://bugs.python.org/review/15831/diff/5943/Doc/library/functions.rst#newcode983
Doc/library/functions.rst:983: .. function:: print(*objects, sep=' ',
end='\\n', file=sys.stdout, flush=False)
On 2012/09/05 14:15:29, ezio.melotti wrote:
> Why the * is missing here?

The first argument *objects already receives all remaining positional
arguments (since it itself has a *), so putting an additional * after
*objects would be redundant.  The single * is only necessary if the
positional arguments portion doesn't end with *identifier.

http://bugs.python.org/review/15831/diff/5943/Doc/library/http.client.rst
File Doc/library/http.client.rst (right):

http://bugs.python.org/review/15831/diff/5943/Doc/library/http.client.rst#newcode31
Doc/library/http.client.rst:31: source_address=None)
On 2012/09/05 14:15:29, ezio.melotti wrote:
> This signature is not too nice, but I'm not sure how it could be
improved.  Is
> strict a bool?  Maybe using timeout=socket.getdefaulttimeout() might
be ok
> (assuming that's what it uses), or if it's set to None or something
similar and
> then re-set to the actual value you could use None in the signature
and describe
> it in prose later.

I believe this is the best we can do to be correct.  Here is the actual
signature:

def __init__(self, host, port=None, strict=_strict_sentinel,
             timeout=socket._GLOBAL_DEFAULT_TIMEOUT,
source_address=None):
 
The two arguments in question default to private sentinel values.  I
think it is at least an improvement over the old signature which had
triply nested brackets.



Please review this at http://bugs.python.org/review/15831/

Affected files:
  Doc/library/argparse.rst
  Doc/library/configparser.rst
  Doc/library/curses.rst
  Doc/library/functions.rst
  Doc/library/http.client.rst
  Doc/library/inspect.rst
  Doc/library/itertools.rst
  Doc/library/multiprocessing.rst
  Doc/library/optparse.rst
  Doc/library/ossaudiodev.rst
  Doc/library/random.rst
  Doc/library/socket.rst
  Doc/library/stdtypes.rst
  Doc/library/syslog.rst
  Doc/library/tkinter.tix.rst