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

11 files changed, 79 insertions, 40 deletions

diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst
index 36f4da2..8bb740e 100644
--- 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/curses.rst b/Doc/library/curses.rst
index ecdac9a..a3c098b 100644
--- a/Doc/library/curses.rst
+++ b/Doc/library/curses.rst
@@ -380,7 +380,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*.
@@ -648,7 +649,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::
 
@@ -662,13 +664,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.
@@ -755,7 +759,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,
@@ -804,7 +811,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
@@ -879,7 +887,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*.
@@ -913,7 +922,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.
@@ -934,7 +944,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
@@ -943,7 +954,8 @@ 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
@@ -951,7 +963,8 @@ the following methods:
    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
@@ -1126,13 +1139,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*.
@@ -1189,7 +1204,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
index 8d80271..a86e768 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -753,11 +753,16 @@ available.  They are listed here in alphabetical order.
    the result is always a list.
 
 
-.. 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 *key* argument specifies a one-argument ordering function like that
    used for :meth:`list.sort`.  The *key* argument, if supplied, must be in keyword
@@ -774,11 +779,16 @@ 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 *key* argument specifies a one-argument ordering function like that
    used for :meth:`list.sort`.  The *key* argument, if supplied, must be in keyword
@@ -918,16 +928,16 @@ available.  They are listed here in alphabetical order.
    accidents.)
 
 
-.. 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
@@ -1025,7 +1035,8 @@ available.  They are listed here in alphabetical order.
       The ``getter``, ``setter``, and ``deleter`` attributes were added.
 
 
-.. function:: range([start,] stop[, step])
+.. function:: range(stop)
+              range(start, stop[, step])
 
    This is a versatile function to create lists containing arithmetic progressions.
    It is most often used in :keyword:`for` loops.  The arguments must be plain
@@ -1221,7 +1232,8 @@ 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
 
@@ -1497,7 +1509,8 @@ available.  They are listed here in alphabetical order.
    dictionary are ignored.
 
 
-.. function:: xrange([start,] stop[, step])
+.. function:: xrange(stop)
+              xrange(start, stop[, step])
 
    This function is very similar to :func:`range`, but returns an "xrange object"
    instead of a list.  This is an opaque sequence type which yields the same values
diff --git a/Doc/library/itertools.rst b/Doc/library/itertools.rst
index c144b3e..8bb9e36 100644
--- a/Doc/library/itertools.rst
+++ b/Doc/library/itertools.rst
@@ -393,7 +393,8 @@ loops that truncate the stream.
                   yield function(*args)
 
 
-.. 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
index bac9cf0..7c28951 100644
--- 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
index c14b790..d5a35c2 100644
--- a/Doc/library/optparse.rst
+++ b/Doc/library/optparse.rst
@@ -275,7 +275,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.
@@ -895,7 +896,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
index 08f118f..c5404de 100644
--- a/Doc/library/ossaudiodev.rst
+++ b/Doc/library/ossaudiodev.rst
@@ -66,7 +66,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
index 29f0e6a..b1df231 100644
--- a/Doc/library/random.rst
+++ b/Doc/library/random.rst
@@ -124,7 +124,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
index f9e5e03..f6dc4f0 100644
--- a/Doc/library/socket.rst
+++ b/Doc/library/socket.rst
@@ -739,7 +739,8 @@ correspond to Unix system calls applicable to sockets.
    much data, if any, was successfully sent.
 
 
-.. method:: socket.sendto(string[, flags], address)
+.. method:: socket.sendto(string, address)
+            socket.sendto(string, 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
index 780ca59..9b66abf 100644
--- 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/tix.rst b/Doc/library/tix.rst
index ed68e81..a2f31a0 100644
--- a/Doc/library/tix.rst
+++ b/Doc/library/tix.rst
@@ -514,7 +514,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