iSharkFly-Open
/
python-peps
mirror of https://github.com/python/peps.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

New version from David Goodger, where he makes me co-author (since 

it's mostly lifted from my style guide).  I don't plan to actively
contribute much -- David is the primary author.

There are many miscellaneous updates here.
This commit is contained in:
Guido van Rossum 2001-06-18 19:18:58 +00:00
parent 9bab4aa88d
commit d96e4fbc05
1 changed files with 88 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

154
pep-0257.txt
View File

@ -2,12 +2,13 @@ PEP: 257
Title: Docstring Conventions
Version: $Revision$
Last-Modified: $Date$
Author: dgoodger@bigfoot.com (David Goodger)
Author: dgoodger@bigfoot.com (David Goodger),
guido@digicool.com (Guido van Rossum)
Discussions-To: doc-sig@python.org
Status: Draft
Type: Informational
Created: 29-May-2001
Post-History:
Post-History: 13-Jun-2001
Abstract
@ -16,31 +17,60 @@ Abstract
Python docstrings.
Rationale
The aim of this PEP is to standardize the high-level structure of
docstrings: what they should contain, and how to say it (without
touching on any markup syntax within docstrings). The PEP
contains conventions, not laws or syntax.
"A universal convention supplies all of maintainability,
clarity, consistency, and a foundation for good programming
habits too. What it doesn't do is insist that you follow it
against your will. That's Python!"
--Tim Peters on comp.lang.python, 2001-06-16
If you violate the conventions, the worst you'll get is some dirty
looks. But some software (such as the Docstring Processing System
[1]) will be aware of the conventions, so following them will get
you the best results.
Specification
What is a Docstring?
--------------------
A docstring is a string literal that occurs as the first statement
in a module, function, class, or method definition. Such a
docstring becomes the __doc__ special attribute of that object.
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.
docstrings. A package may be documented in the module docstring
of the __init__.py file in the package directory.
[+] A package may be documented in the module docstring of the
[+] __init__.py file in the package directory.
String literals occuring elsewhere in Python code may also act as
documentation. They are not recognized by the Python bytecode
compiler and are not accessible as runtime object attributes
(i.e. not assigned to __doc__), but two types of extra docstrings
are recognized by software tools:
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.
1. String literals occuring immediately after a simple assignment
at the top level of a module, class, or __init__ method
are called "attribute docstrings".
2. String literals occuring immediately after another docstring
are called "additional docstrings".
Please see PEP 258 "DPS Generic Implementation Details" [2] for a
detailed description of attribute and additional docstrings.
For consistency, always use """triple double quotes""" around
docstrings.
[+] Use r"""raw triple double quotes""" if you use any
[+] backslashes in your docstrings.
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.
@ -49,7 +79,7 @@ Specification
--------------------
One-liners are for really obvious cases. They should really fit
on one line. For example:
on one line. For example::
def kos_root():
"""Return the pathname of the KOS root directory."""
@ -65,21 +95,21 @@ Specification
- 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.
- 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.
- 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
----------------------
@ -108,11 +138,23 @@ Specification
case, treat the docstring as another section, and precede it with
a blank line.
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.
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.)
docstring.) The docstring for a package (i.e., the docstring of
the package's __init__.py module) should also list the modules and
subpackages exported by the package.
The docstring for a function or method should summarize its
behavior and document its arguments, return value(s), side
@ -141,10 +183,8 @@ Specification
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:
names. It is best to list each argument on a separate line. For
example::
def complex(real=0.0, imag=0.0):
"""Form a complex number.
@ -157,27 +197,24 @@ Specification
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]
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.
References and Footnotes
[1] http://www.python.org/doc/essays/styleguide.html
[1] http://python.sf.net/peps/pep-0256.html
[2] http://www.python.org/sigs/doc-sig/
[2] http://python.sf.net/peps/pep-0258.html
[3] Guido van Rossum, Python's Benevolent Dictator For Life.
[3] Guido van Rossum, Python's creator and Benevolent Dictator For
Life.
[4] http://python.sf.net/peps/pep-0258.html
[4] http://www.python.org/doc/essays/styleguide.html
[5] http://www.python.org/sigs/doc-sig/
Copyright
@ -188,22 +225,7 @@ Copyright
Acknowledgements
The "Specification" text comes mostly verbatim from the Python
Style Guide by Guido van Rossum [1].
Style Guide by Guido van Rossum [4].
(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:
This document borrows ideas from the archives of the Python
Doc-SIG [5]. Thanks to all members past and present.