[Python-checkins] cpython (2.7): #15831: document multiple signatures on different lines. Patch by Chris
ezio.melotti
python-checkins at python.org
Fri Sep 14 06:01:37 CEST 2012
http://hg.python.org/cpython/rev/2291aff20a05
changeset: 79025:2291aff20a05
branch: 2.7
parent: 79022:76dd082d332e
user: Ezio Melotti <ezio.melotti at gmail.com>
date: Fri Sep 14 06:48:32 2012 +0300
summary:
#15831: document multiple signatures on different lines. Patch by Chris Jerdonek.
files:
Doc/library/argparse.rst | 9 ++-
Doc/library/curses.rst | 44 ++++++++++++++------
Doc/library/functions.rst | 41 ++++++++++++------
Doc/library/itertools.rst | 3 +-
Doc/library/multiprocessing.rst | 2 +-
Doc/library/optparse.rst | 6 +-
Doc/library/ossaudiodev.rst | 3 +-
Doc/library/random.rst | 3 +-
Doc/library/socket.rst | 3 +-
Doc/library/syslog.rst | 3 +-
Doc/library/tix.rst | 2 +-
11 files changed, 79 insertions(+), 40 deletions(-)
diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst
--- a/Doc/library/argparse.rst
+++ b/Doc/library/argparse.rst
@@ -130,9 +130,12 @@
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
--- a/Doc/library/curses.rst
+++ b/Doc/library/curses.rst
@@ -380,7 +380,8 @@
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 @@
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 @@
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 @@
*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 @@
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 @@
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 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 @@
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 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 @@
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 @@
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 @@
: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
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -753,11 +753,16 @@
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 @@
:ref:`typememoryview` for more information.
-.. function:: min(iterable[, args...][key])
+.. function:: min(iterable, *[, key])
+ min(arg1, arg2, *args[, key])
- 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.
+ Return the smallest item in an iterable or the smallest 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 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 @@
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 @@
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 @@
``x.foobar = 123``.
-.. function:: slice([start,] stop[, step])
+.. function:: slice(stop)
+ slice(start, stop[, step])
.. index:: single: Numerical Python
@@ -1497,7 +1509,8 @@
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
--- a/Doc/library/itertools.rst
+++ b/Doc/library/itertools.rst
@@ -393,7 +393,8 @@
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
--- a/Doc/library/multiprocessing.rst
+++ b/Doc/library/multiprocessing.rst
@@ -298,7 +298,7 @@
: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
--- a/Doc/library/optparse.rst
+++ b/Doc/library/optparse.rst
@@ -275,7 +275,8 @@
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 @@
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
--- a/Doc/library/ossaudiodev.rst
+++ b/Doc/library/ossaudiodev.rst
@@ -66,7 +66,8 @@
``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
--- a/Doc/library/random.rst
+++ b/Doc/library/random.rst
@@ -124,7 +124,8 @@
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
--- a/Doc/library/socket.rst
+++ b/Doc/library/socket.rst
@@ -739,7 +739,8 @@
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
--- a/Doc/library/syslog.rst
+++ b/Doc/library/syslog.rst
@@ -17,7 +17,8 @@
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
--- a/Doc/library/tix.rst
+++ b/Doc/library/tix.rst
@@ -514,7 +514,7 @@
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
--
Repository URL: http://hg.python.org/cpython
More information about the Python-checkins
mailing list