#15831: document multiple signatures on different lines. Patch by Chris Jerdonek.

ezio-melotti · ezio-melotti · commit e0add764688a · 2012-09-14T06:32:35.000+03:00
diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst
@@ -130,9 +130,12 @@ command-line arguments from :data:`sys.argv`.
 ArgumentParser objects
 ----------------------
 
-.. class:: ArgumentParser([description], [epilog], [prog], [usage], [add_help], \
-                          [argument_default], [parents], [prefix_chars], \
-                          [conflict_handler], [formatter_class])
+.. class:: ArgumentParser(prog=None, usage=None, description=None, \
+                          epilog=None, parents=[], \
+                          formatter_class=argparse.HelpFormatter, \
+                          prefix_chars='-', fromfile_prefix_chars=None, \
+                          argument_default=None, conflict_handler='error', \
+                          add_help=True)
 
    Create a new :class:`ArgumentParser` object.  Each parameter has its own more
    detailed description below, but in short they are:
diff --git a/Doc/library/configparser.rst b/Doc/library/configparser.rst
@@ -1051,7 +1051,8 @@ ConfigParser Objects
       *fallback*.
 
 
-   .. method:: items([section], raw=False, vars=None)
+   .. method:: items(raw=False, vars=None)
+               items(section, raw=False, vars=None)
 
       When *section* is not given, return a list of *section_name*,
       *section_proxy* pairs, including DEFAULTSECT.
diff --git a/Doc/library/curses.rst b/Doc/library/curses.rst
@@ -377,7 +377,8 @@ The module :mod:`curses` defines the following functions:
    is to be displayed.
 
 
-.. function:: newwin([nlines, ncols,] begin_y, begin_x)
+.. function:: newwin(begin_y, begin_x)
+              newwin(nlines, ncols, begin_y, begin_x)
 
    Return a new window, whose left-upper corner is at  ``(begin_y, begin_x)``, and
    whose height/width is  *nlines*/*ncols*.
@@ -645,7 +646,8 @@ Window objects, as returned by :func:`initscr` and :func:`newwin` above, have
 the following methods:
 
 
-.. method:: window.addch([y, x,] ch[, attr])
+.. method:: window.addch(ch[, attr])
+            window.addch(y, x, ch[, attr])
 
    .. note::
 
@@ -659,13 +661,15 @@ the following methods:
    position and attributes are the current settings for the window object.
 
 
-.. method:: window.addnstr([y, x,] str, n[, attr])
+.. method:: window.addnstr(str, n[, attr])
+            window.addnstr(y, x, str, n[, attr])
 
    Paint at most *n* characters of the  string *str* at ``(y, x)`` with attributes
    *attr*, overwriting anything previously on the display.
 
 
-.. method:: window.addstr([y, x,] str[, attr])
+.. method:: window.addstr(str[, attr])
+            window.addstr(y, x, str[, attr])
 
    Paint the string *str* at ``(y, x)`` with attributes *attr*, overwriting
    anything previously on the display.
@@ -752,7 +756,10 @@ the following methods:
    *bs* are *horch*.  The default corner characters are always used by this function.
 
 
-.. method:: window.chgat([y, x, ] [num,] attr)
+.. method:: window.chgat(attr)
+            window.chgat(num, attr)
+            window.chgat(y, x, attr)
+            window.chgat(y, x, num, attr)
 
    Set the attributes of *num* characters at the current cursor position, or at
    position ``(y, x)`` if supplied. If no value of *num* is given or *num* = -1,
@@ -801,7 +808,8 @@ the following methods:
    Delete the line under the cursor. All following lines are moved up by one line.
 
 
-.. method:: window.derwin([nlines, ncols,] begin_y, begin_x)
+.. method:: window.derwin(begin_y, begin_x)
+            window.derwin(nlines, ncols, begin_y, begin_x)
 
    An abbreviation for "derive window", :meth:`derwin` is the same as calling
    :meth:`subwin`, except that *begin_y* and *begin_x* are relative to the origin
@@ -876,7 +884,8 @@ the following methods:
    upper-left corner.
 
 
-.. method:: window.hline([y, x,] ch, n)
+.. method:: window.hline(ch, n)
+            window.hline(y, x, ch, n)
 
    Display a horizontal line starting at ``(y, x)`` with length *n* consisting of
    the character *ch*.
@@ -910,7 +919,8 @@ the following methods:
    the character proper, and upper bits are the attributes.
 
 
-.. method:: window.insch([y, x,] ch[, attr])
+.. method:: window.insch(ch[, attr])
+            window.insch(y, x, ch[, attr])
 
    Paint character *ch* at ``(y, x)`` with attributes *attr*, moving the line from
    position *x* right by one character.
@@ -931,7 +941,8 @@ the following methods:
    line.
 
 
-.. method:: window.insnstr([y, x,] str, n [, attr])
+.. method:: window.insnstr(str, n[, attr])
+            window.insnstr(y, x, str, n[, attr])
 
    Insert a character string (as many characters as will fit on the line) before
    the character under the cursor, up to *n* characters.   If *n* is zero or
@@ -940,15 +951,17 @@ the following methods:
    The cursor position does not change (after moving to *y*, *x*, if specified).
 
 
-.. method:: window.insstr([y, x, ] str [, attr])
+.. method:: window.insstr(str[, attr])
+            window.insstr(y, x, str[, attr])
 
    Insert a character string (as many characters as will fit on the line) before
    the character under the cursor.  All characters to the right of the cursor are
    shifted right, with the rightmost characters on the line being lost.  The cursor
    position does not change (after moving to *y*, *x*, if specified).
 
 
-.. method:: window.instr([y, x] [, n])
+.. method:: window.instr([n])
+            window.instr(y, x[, n])
 
    Return a string of characters, extracted from the window starting at the
    current cursor position, or at *y*, *x* if specified. Attributes are stripped
@@ -1123,13 +1136,15 @@ the following methods:
    Turn on attribute *A_STANDOUT*.
 
 
-.. method:: window.subpad([nlines, ncols,] begin_y, begin_x)
+.. method:: window.subpad(begin_y, begin_x)
+            window.subpad(nlines, ncols, begin_y, begin_x)
 
    Return a sub-window, whose upper-left corner is at ``(begin_y, begin_x)``, and
    whose width/height is *ncols*/*nlines*.
 
 
-.. method:: window.subwin([nlines, ncols,] begin_y, begin_x)
+.. method:: window.subwin(begin_y, begin_x)
+            window.subwin(nlines, ncols, begin_y, begin_x)
 
    Return a sub-window, whose upper-left corner is at ``(begin_y, begin_x)``, and
    whose width/height is *ncols*/*nlines*.
@@ -1186,7 +1201,8 @@ the following methods:
    :meth:`refresh`.
 
 
-.. method:: window.vline([y, x,] ch, n)
+.. method:: window.vline(ch, n)
+            window.vline(y, x, ch, n)
 
    Display a vertical line starting at ``(y, x)`` with length *n* consisting of the
    character *ch*.
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
@@ -727,11 +727,16 @@ are always available.  They are listed here in alphabetical order.
    already arranged into argument tuples, see :func:`itertools.starmap`\.
 
 
-.. function:: max(iterable[, args...], *[, key])
+.. function:: max(iterable, *[, key])
+              max(arg1, arg2, *args[, key])
 
-   With a single argument *iterable*, return the largest item of a non-empty
-   iterable (such as a string, tuple or list).  With more than one argument, return
-   the largest of the arguments.
+   Return the largest item in an iterable or the largest of two or more
+   arguments.
+
+   If one positional argument is provided, *iterable* must be a non-empty
+   iterable (such as a non-empty string, tuple or list).  The largest item
+   in the iterable is returned.  If two or more positional arguments are
+   provided, the largest of the positional arguments is returned.
 
    The optional keyword-only *key* argument specifies a one-argument ordering
    function like that used for :meth:`list.sort`.
@@ -750,11 +755,16 @@ are always available.  They are listed here in alphabetical order.
    :ref:`typememoryview` for more information.
 
 
-.. function:: min(iterable[, args...], *[, key])
+.. function:: min(iterable, *[, key])
+              min(arg1, arg2, *args[, key])
+
+   Return the smallest item in an iterable or the smallest of two or more
+   arguments.
 
-   With a single argument *iterable*, return the smallest item of a non-empty
-   iterable (such as a string, tuple or list).  With more than one argument, return
-   the smallest of the arguments.
+   If one positional argument is provided, *iterable* must be a non-empty
+   iterable (such as a non-empty string, tuple or list).  The smallest item
+   in the iterable is returned.  If two or more positional arguments are
+   provided, the smallest of the positional arguments is returned.
 
    The optional keyword-only *key* argument specifies a one-argument ordering
    function like that used for :meth:`list.sort`.
@@ -957,16 +967,16 @@ are always available.  They are listed here in alphabetical order.
    must be of integer types, and *y* must be non-negative.
 
 
-.. function:: print([object, ...], *, sep=' ', end='\\n', file=sys.stdout)
+.. function:: print(*objects, sep=' ', end='\\n', file=sys.stdout)
 
-   Print *object*\(s) to the stream *file*, separated by *sep* and followed by
+   Print *objects* to the stream *file*, separated by *sep* and followed by
    *end*.  *sep*, *end* and *file*, if present, must be given as keyword
    arguments.
 
    All non-keyword arguments are converted to strings like :func:`str` does and
    written to the stream, separated by *sep* and followed by *end*.  Both *sep*
    and *end* must be strings; they can also be ``None``, which means to use the
-   default values.  If no *object* is given, :func:`print` will just write
+   default values.  If no *objects* are given, :func:`print` will just write
    *end*.
 
    The *file* argument must be an object with a ``write(string)`` method; if it
@@ -1045,7 +1055,8 @@ are always available.  They are listed here in alphabetical order.
 
 
 .. XXX does accept objects with __index__ too
-.. function:: range([start,] stop[, step])
+.. function:: range(stop)
+              range(start, stop[, step])
 
    This is a versatile function to create iterables yielding arithmetic
    progressions.  It is most often used in :keyword:`for` loops.  The arguments
@@ -1160,7 +1171,8 @@ are always available.  They are listed here in alphabetical order.
    ``x.foobar = 123``.
 
 
-.. function:: slice([start,] stop[, step])
+.. function:: slice(stop)
+              slice(start, stop[, step])
 
    .. index:: single: Numerical Python
 
diff --git a/Doc/library/http.client.rst b/Doc/library/http.client.rst
@@ -27,7 +27,8 @@ HTTPS protocols.  It is normally not used directly --- the module
 The module provides the following classes:
 
 
-.. class:: HTTPConnection(host, port=None[, strict[, timeout[, source_address]]])
+.. class:: HTTPConnection(host, port=None[, strict][, timeout], \
+                          source_address=None)
 
    An :class:`HTTPConnection` instance represents one transaction with an HTTP
    server.  It should be instantiated passing it a host and optional port
@@ -55,7 +56,10 @@ The module provides the following classes:
       are not supported anymore.
 
 
-.. class:: HTTPSConnection(host, port=None, key_file=None, cert_file=None[, strict[, timeout[, source_address]]], *, context=None, check_hostname=None)
+.. class:: HTTPSConnection(host, port=None, key_file=None, \
+                           cert_file=None[, strict][, timeout], \
+                           source_address=None, *, context=None, \
+                           check_hostname=None)
 
    A subclass of :class:`HTTPConnection` that uses SSL for communication with
    secure servers.  Default port is ``443``.  If *context* is specified, it
diff --git a/Doc/library/itertools.rst b/Doc/library/itertools.rst
@@ -363,7 +363,8 @@ loops that truncate the stream.
                   self.currkey = self.keyfunc(self.currvalue)
 
 
-.. function:: islice(iterable, [start,] stop [, step])
+.. function:: islice(iterable, stop)
+              islice(iterable, start, stop[, step])
 
    Make an iterator that returns selected elements from the iterable. If *start* is
    non-zero, then elements from the iterable are skipped until start is reached.
diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst
@@ -298,7 +298,7 @@ The :mod:`multiprocessing` package mostly replicates the API of the
 :class:`Process` and exceptions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. class:: Process([group[, target[, name[, args[, kwargs]]]]])
+.. class:: Process(group=None, target=None, name=None, args=(), kwargs={})
 
    Process objects represent activity that is run in a separate process. The
    :class:`Process` class has equivalents of all the methods of
diff --git a/Doc/library/optparse.rst b/Doc/library/optparse.rst
@@ -273,7 +273,8 @@ You're free to define as many short option strings and as many long option
 strings as you like (including zero), as long as there is at least one option
 string overall.
 
-The option strings passed to :meth:`add_option` are effectively labels for the
+The option strings passed to :meth:`OptionParser.add_option` are effectively
+labels for the
 option defined by that call.  For brevity, we will frequently refer to
 *encountering an option* on the command line; in reality, :mod:`optparse`
 encounters *option strings* and looks up options from them.
@@ -892,7 +893,8 @@ long option strings, but you must specify at least one overall option string.
 The canonical way to create an :class:`Option` instance is with the
 :meth:`add_option` method of :class:`OptionParser`.
 
-.. method:: OptionParser.add_option(opt_str[, ...], attr=value, ...)
+.. method:: OptionParser.add_option(option)
+            OptionParser.add_option(*opt_str, attr=value, ...)
 
    To define an option with only a short option string::
 
diff --git a/Doc/library/ossaudiodev.rst b/Doc/library/ossaudiodev.rst
@@ -63,7 +63,8 @@ the standard audio interface for Linux and recent versions of FreeBSD.
    ``ossaudiodev.error``.)
 
 
-.. function:: open([device, ]mode)
+.. function:: open(mode)
+              open(device, mode)
 
    Open an audio device and return an OSS audio device object.  This object
    supports many file-like methods, such as :meth:`read`, :meth:`write`, and
diff --git a/Doc/library/random.rst b/Doc/library/random.rst
@@ -46,20 +46,20 @@ from sources provided by the operating system.
 
 Bookkeeping functions:
 
-.. function:: seed([x], version=2)
+.. function:: seed(a=None, version=2)
 
    Initialize the random number generator.
 
-   If *x* is omitted or ``None``, the current system time is used.  If
+   If *a* is omitted or ``None``, the current system time is used.  If
    randomness sources are provided by the operating system, they are used
    instead of the system time (see the :func:`os.urandom` function for details
    on availability).
 
-   If *x* is an int, it is used directly.
+   If *a* is an int, it is used directly.
 
    With version 2 (the default), a :class:`str`, :class:`bytes`, or :class:`bytearray`
    object gets converted to an :class:`int` and all of its bits are used.  With version 1,
-   the :func:`hash` of *x* is used instead.
+   the :func:`hash` of *a* is used instead.
 
    .. versionchanged:: 3.2
       Moved to the version 2 scheme which uses all of the bits in a string seed.
@@ -87,7 +87,8 @@ Bookkeeping functions:
 
 Functions for integers:
 
-.. function:: randrange([start,] stop[, step])
+.. function:: randrange(stop)
+              randrange(start, stop[, step])
 
    Return a randomly selected element from ``range(start, stop, step)``.  This is
    equivalent to ``choice(range(start, stop, step))``, but doesn't actually build a
diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst
@@ -745,7 +745,8 @@ correspond to Unix system calls applicable to sockets.
    much data, if any, was successfully sent.
 
 
-.. method:: socket.sendto(bytes[, flags], address)
+.. method:: socket.sendto(bytes, address)
+            socket.sendto(bytes, flags, address)
 
    Send data to the socket.  The socket should not be connected to a remote socket,
    since the destination socket is specified by *address*.  The optional *flags*
diff --git a/Doc/library/syslog.rst b/Doc/library/syslog.rst
@@ -17,7 +17,8 @@ library that can speak to a syslog server is available in the
 The module defines the following functions:
 
 
-.. function:: syslog([priority,] message)
+.. function:: syslog(message)
+              syslog(priority, message)
 
    Send the string *message* to the system logger.  A trailing newline is added
    if necessary.  Each message is tagged with a priority composed of a
diff --git a/Doc/library/tkinter.tix.rst b/Doc/library/tkinter.tix.rst
@@ -504,7 +504,7 @@ Tix Commands
       print(root.tix_configure())
 
 
-.. method:: tixCommand.tix_configure([cnf,] **kw)
+.. method:: tixCommand.tix_configure(cnf=None, **kw)
 
    Query or modify the configuration options of the Tix application context. If no
    option is specified, returns a dictionary all of the available options.  If
