From 3cade7a68baa4160b49d490883ed9f2664e1b95a Mon Sep 17 00:00:00 2001 From: unknown Date: Wed, 6 Jun 2001 05:55:20 +0000 Subject: [PATCH] PEP 257, Docstring Conventions, David Goodger Editing pass by Barry. --- pep-0257.txt | 209 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 209 insertions(+) create mode 100644 pep-0257.txt diff --git a/pep-0257.txt b/pep-0257.txt new file mode 100644 index 000000000..77cee4182 --- /dev/null +++ b/pep-0257.txt @@ -0,0 +1,209 @@ +PEP: 257 +Title: Docstring Conventions +Version: $Revision$ +Last-Modified: $Date$ +Author: dgoodger@bigfoot.com (David Goodger) +Discussions-To: doc-sig@python.org +Status: Draft +Type: Informational +Created: 29-May-2001 +Post-History: + + +Abstract + + This PEP documents the semantics and conventions associated with + Python docstrings. + + +Specification + + All modules should normally have docstrings, and all functions and + classes exported by a module should also have docstrings. Public + methods (including the __init__ constructor) should also have + docstrings. + + [+] A package may be documented in the module docstring of the + [+] __init__.py file in the package directory. + + The docstring of a script (a stand-alone program) should be usable + as its "usage" message, printed when the script is invoked with + incorrect or missing arguments (or perhaps with a "-h" option, for + "help"). Such a docstring should document the script's function + and command line syntax, environment variables, and files. Usage + messages can be fairly elaborate (several screens full) and should + be sufficient for a new user to use the command properly, as well + as a complete quick reference to all options and arguments for the + sophisticated user. + + For consistency, always use """triple double quotes""" around + docstrings. + + [+] Use r"""raw triple double quotes""" if you use any + [+] backslashes in your docstrings. + + There are two forms of docstrings: one-liners and multi-line + docstrings. + + One-line Docstrings + -------------------- + + One-liners are for really obvious cases. They should really fit + on one line. For example: + + def kos_root(): + """Return the pathname of the KOS root directory.""" + global _kos_root + if _kos_root: return _kos_root + ... + + Notes: + + - Triple quotes are used even though the string fits on one line. + This makes it easy to later expand it. + + - The closing quotes are on the same line as the opening quotes. + This looks better for one-liners. + + - There's no blank line either before or after the docstring. + + - The docstring is a phrase ending in a period. It prescribes the + function's effect as a command ("Do this", "Return that"), not + as a description: e.g. don't write "Returns the pathname ..." + + [+] - The one-line docstring should NOT be a "signature" reiterating + [+] the function parameters (which can be obtained by introspection). + [+] Don't do: + + [+] def function(a, b): + [+] """function(a, b) -> list""" + + [+] This type of docstring is only appropriate for C functions (such + [+] as built-ins), where introspection is not possible. + + Multi-line Docstrings + ---------------------- + + Multi-line docstrings consist of a summary line just like a + one-line docstring, followed by a blank line, followed by a more + elaborate description. The summary line may be used by automatic + indexing tools; it is important that it fits on one line and is + separated from the rest of the docstring by a blank line. + + The entire docstring is indented the same as the quotes at its + first line (see example below). Docstring processing tools will + strip an amount of indentation from the second and further lines + of the docstring equal to the indentation of the first non-blank + line after the first line of the docstring. Relative indentation + of later lines in the docstring is retained. + + Insert a blank line before and after all docstrings (one-line or + multi-line) that document a class -- generally speaking, the + class's methods are separated from each other by a single blank + line, and the docstring needs to be offset from the first method + by a blank line; for symmetry, put a blank line between the class + header and the docstring. Docstrings documenting functions + generally don't have this requirement, unless the function's body + is written as a number of blank-line separated sections -- in this + case, treat the docstring as another section, and precede it with + a blank line. + + The docstring for a module should generally list the classes, + exceptions and functions (and any other objects) that are exported + by the module, with a one-line summary of each. (These summaries + generally give less detail than the summary line in the object's + docstring.) + + The docstring for a function or method should summarize its + behavior and document its arguments, return value(s), side + effects, exceptions raised, and restrictions on when it can be + called (all if applicable). Optional arguments should be + indicated. It should be documented whether keyword arguments are + part of the interface. + + The docstring for a class should summarize its behavior and list + the public methods and instance variables. If the class is + intended to be subclassed, and has an additional interface for + subclasses, this interface should be listed separately (in the + docstring). The class constructor should be documented in the + docstring for its __init__ method. Individual methods should be + documented by their own docstring. + + If a class subclasses another class and its behavior is mostly + inherited from that class, its docstring should mention this and + summarize the differences. Use the verb "override" to indicate + that a subclass method replaces a superclass method and does not + call the superclass method; use the verb "extend" to indicate that + a subclass method calls the superclass method (in addition to its + own behavior). + + *Do not* use the Emacs convention of mentioning the arguments of + functions or methods in upper case in running text. Python is + case sensitive and the argument names can be used for keyword + arguments, so the docstring should document the correct argument + names. It is best to list each argument on a separate line, + + [-] with two dashes separating the name from the description, + [-] like this: + + def complex(real=0.0, imag=0.0): + """Form a complex number. + + Keyword arguments: + real -- the real part (default 0.0) + imag -- the imaginary part (default 0.0) + + """ + if imag == 0.0 and real == 0.0: return complex_zero + ... + + [-] The BDFL [3] recommends inserting a blank line between the + [-] last paragraph in a multi-line docstring and its closing quotes, + [-] placing the closing quotes on a line by themselves. This way, + [-] Emacs' fill-paragraph command can be used on it. + + [+] Attribute Docstrings: see PEP 258, "DPS Generic Implementation + [+] Details" [4] + + [+] Additional Docstrings: see PEP 258, "DPS Generic Implementation + [+] Details" [4] + + +References and Footnotes + + [1] http://www.python.org/doc/essays/styleguide.html + + [2] http://www.python.org/sigs/doc-sig/ + + [3] Guido van Rossum, Python's Benevolent Dictator For Life. + + [4] http://python.sf.net/peps/pep-0258.html + + +Copyright + + This document has been placed in the public domain. + + +Acknowledgements + + The "Specification" text comes mostly verbatim from the Python + Style Guide by Guido van Rossum [1]. + + (If it's OK with him, I will add GvR as an author of this PEP. I + am quite confident that the BDFL doesn't want to own this PEP :-). + Apart from minor editing, proposed additions to the Style Guide + text are marked with '[+]' to the left of each line, and proposed + omissions are marked with '[-]'. If it is deemed that this PEP is + unnecessary, then it can be taken as suggestions for Style Guide + modification.) + + This document borrows ideas from the archives of the Python Doc-SIG + [2]. Thanks to all members past and present. + + + +Local Variables: +mode: indented-text +indent-tabs-mode: nil +End: