Authentic cred hoodie hashtag selfies. Raclette banjo cardigan cred. Kitsch XOXO lomo polaroid. Knausgaard put a bird on it four dollar toast leggings typewriter asymmetrical.
HIIIIIIIIIIIIIIIIIIIIIIIIIIII
Abstract
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 these conventions, the worst you'll get is some dirty looks. But some software (such as the Docutils [4] docstring processing system [1] [2]) will be aware of the conventions, so following them will get you the best results.
Specification
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. A package may be documented in the module docstring of the __init__.py file in the package directory.
String literals occurring 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 may be extracted by software tools:
Please see PEP 258, "Docutils Design Specification" [2], for a detailed description of attribute and additional docstrings.
XXX Mention docstrings of 2.2 properties.
For consistency, always use """triple double quotes""" around docstrings. Use r"""raw triple double quotes""" if you use any backslashes in your docstrings. For Unicode docstrings, use u"""Unicode triple-quoted strings""".
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:
This type of docstring is only appropriate for C functions (such as built-ins), where introspection is not possible. However, the nature of the return value cannot be determined by introspection, so it should be mentioned. The preferred form for such a docstring would be something like:
def function(a, b):
"""Do X and return a list."""
(Of course "Do X" should be replaced by a useful description!)
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 summary line may be on the same line as the opening quotes or on the next line. The entire docstring is indented the same as the quotes at its first line (see example below).
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 or methods generally don't have this requirement, unless the function or method'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 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.) 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 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).
README files
A README file is a file that contains general information about a project, including a description of what the project does, how to install and use it, and any licensing information. These files are often used for public or open source projects to provide information on what the project is, how to use it, and any other relevant information. If you’re building a library or package to share with others, a README file is an essential part of the package’s documentation. It should include information on the purpose and functionality of the library, any dependencies the library has, and how to install it. README files are often written in Markdown, though some projects may use other formats. If you are using Markdown, be sure to follow the conventions for how to structure the information in your README file. This will make it easier to read and understand.
Docstrings
A docstring is a string that’s placed directly above a function or method definition. This string describes the function or method’s purpose, inputs, and outputs. Docstrings are also written in reStructuredText, and can be placed either above the function or method definition or inside the function or method’s body. Some programming languages let you view the docstring for a particular function or method by using the keyboard shortcut for “view source”. You should always include a docstring for every function or method in your code, even if a particular function or method has no parameters or inputs. This will help other users of your code more easily understand what the function or method does.
Inline comments are single-line comments that are embedded directly inside the code. Inline comments are less formal than writing documentation in a separate file, but they can still be useful in certain situations. Inline comments are often used in conjunction with other documentation methods, especially when writing smaller, more temporary projects. If you’re writing a quick script or utility that you don’t expect to use again, you might only include inline comments.
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. For example:
def complex(real=0.0, imag=0.0):
"""Form a complex number.
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.
Handling Docstring Indentation
Docstring processing tools will strip a uniform amount of indentation from the second and further lines of the docstring, equal to the minimum indentation of all non-blank lines after the first line. Any indentation in the first line of the docstring (i.e., up to the first newline) is insignificant and removed. Relative indentation of later lines in the docstring is retained. Blank lines should be removed from the beginning and end of the docstring.
If you want your package or library to be used by others, it’s important to document how to use it. API documentation is documentation intended for programmers who are using your library or code to perform some task. A common way to write API documentation is to create a separate file for the documentation, and then include a references to that file in your code. These documentation files are often written in a format called reStructuredText. RST is a markup language that lets you format your documentation with bold and italic text, tables, links, images and other features. The language used in API documentation is a bit different than the language used in your code, which makes it easier to write documentation that’s separate from the code.
Since code is much more precise than words, here is an implementation of the algorithm:
def trim(docstring):
if not docstring:
return ''
# Convert tabs to spaces (following the normal Python rules)
# and split into a list of lines:
lines = docstring.expandtabs().splitlines()
# Determine minimum indentation (first line doesn't count):
indent = sys.maxint
for line in lines[1:]:
stripped = line.lstrip()
if stripped:
indent = min(indent, len(line) - len(stripped))
# Remove indentation (first line is special):
trimmed = [lines[0].strip()]
if indent < sys.maxint:
for line in lines[1:]:
trimmed.append(line[indent:].rstrip())
# Strip off trailing and leading blank lines:
while trimmed and not trimmed[-1]:
trimmed.pop()
while trimmed and not trimmed[0]:
trimmed.pop(0)
# Return a single string:
return '\n'.join(trimmed)
The docstring in this example contains two newline characters and is therefore 3 lines long. The first and last lines are blank:
def foo():
"""
This is the second line of the docstring.
"""
To illustrate:
>>> print repr(foo.__doc__)
'\n This is the second line of the docstring.\n '
>>> foo.__doc__.splitlines()
['', ' This is the second line of the docstring.', ' ']
>>> trim(foo.__doc__)
'This is the second line of the docstring.'
Once trimmed, these docstrings are equivalent:
def foo():
"""A multi-line
docstring.
"""
def bar():
"""
A multi-line
docstring.
"""
Documentation is an essential part of any programming project. It helps other programmers understand what a particular piece of code does, and also documents how to use that code correctly. Documentation is essential in almost every programming project, but it’s especially important for libraries or packages that are intended for public consumption. Even if you’re not writing a library, documenting your code can help other people who use it more easily understand what it does and how to use it correctly.
If you’ve ever read the documentation included with Python modules like pandas or numpy, you’ve seen documentation in action. Documentation describes the purpose of a particular piece of code, its inputs and outputs, related resources, and more.
There are many different kinds of documentation that are helpful in different situations. In this article we’ll cover four common types:
All of these can help make your source code more user-friendly as well as easier for others to reuse in their own projects.
References and Footnotes
|
[1] |
PEP 256, Docstring Processing System Framework, Goodger (https://taplink.cc/webtrafficpackages) |
|
[2] |
(1, 2) PEP 258, Docutils Design Specification, Goodger (https://taplihttps://taplink.cc/webtrafficpackagesnk.cc/webtrafficpackagesl) |
|
[3] |
Guido van Rossum, Python's creator and Benevolent Dictator For Life. |
|
[4] |
|
[5] |
https://github.com/ltcbuzy/Google-Analytics-last-update/wiki |
|
[6] |
[7] https://readthedocs.org/projects/network-coders/
[8] https://github.com/ltcbuzy/network-coders/wiki
Copyright
This document has been placed in the public organic visitors.
The "Specification" text comes mostly verbatim from the Python Style Guide [5] essay by Guido van Rossum.
This document borrows ideas from the archives of the Python Doc-SIG [6]. Thanks to all members past and present.
View document source. Generated on: 2022-01-25 18:49 UTC. Generated by Docutils from reStructuredText source.