From e0add764688a3f3237749e0c2830b669d2c76ca0 Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Fri, 14 Sep 2012 06:32:35 +0300 Subject: #15831: document multiple signatures on different lines. Patch by Chris Jerdonek. --- Doc/library/argparse.rst | 9 ++++++--- Doc/library/configparser.rst | 3 ++- Doc/library/curses.rst | 44 ++++++++++++++++++++++++++++------------- Doc/library/functions.rst | 38 +++++++++++++++++++++++------------ Doc/library/http.client.rst | 8 ++++++-- Doc/library/itertools.rst | 3 ++- Doc/library/multiprocessing.rst | 2 +- Doc/library/optparse.rst | 6 ++++-- Doc/library/ossaudiodev.rst | 3 ++- Doc/library/random.rst | 11 ++++++----- Doc/library/socket.rst | 3 ++- Doc/library/syslog.rst | 3 ++- Doc/library/tkinter.tix.rst | 2 +- 13 files changed, 89 insertions(+), 46 deletions(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 6aaa36e..1313e4b 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/configparser.rst b/Doc/library/configparser.rst index 6f0ae6a..c202cf2 100644 --- 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 index f31b9c5..11ab5d0 100644 --- 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,7 +951,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 @@ -948,7 +960,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 @@ -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 index b3238b1..be5d4c7 100644 --- 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 index 52fbe57..d439f24 100644 --- 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 index d1d1188..308f925 100644 --- 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 index 18302a7..4271fc2 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 6dc57bb..6a03edf 100644 --- 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 index cf302cc..ed84413 100644 --- 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 index 3a7f131..1cd4d26 100644 --- 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 index 0aef183..344a29f 100644 --- 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 index 645c326..974ecf9 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/tkinter.tix.rst b/Doc/library/tkinter.tix.rst index 289bffd..9de73ad 100644 --- 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 -- cgit v0.12