Docstring

In programming, a docstring is a string literal specified in source code that is used, like a comment, to document a specific segment of code. Unlike conventional source code comments, or even specifically formatted comments like Javadoc documentation, docstrings are not stripped from the source tree when it is parsed, but are retained throughout the runtime of the program. This allows the program to inspect these comments at run time, for instance as an interactive help system, or as metadata.

Languages that support docstrings include Python, Lisp, and Clojure^[1].

Implementation examples

Lisp

In Lisp, docstrings are known as documentation strings. The Common Lisp standard states that a particular implementation may choose to discard docstrings whenever they want, for whatever reason. When they are kept, docstrings may be viewed (and changed) using the DOCUMENTATION function. For instance,

 (defun foo () "hi there" nil)
 (documentation #'foo 'function) => "hi there"

Python

The common practice of placing a comment at the head of definitions when programming, is captured by the addition of docstring syntax in the Python language.

Python docstrings appear as a string literal, (not an expression), as the first statement following the definition of functions, methods, modules, and classes. Docstrings can be accessed by the __doc__ attribute on objects.

The following Python file shows the declaration of docstrings within a python source file:

"""
Assuming this is file mymodule.py, then this string, being the
first statement in the file, will become the "mymodule" module's
docstring when the file is imported.
"""
 
class MyClass(object):
    """The class's docstring"""
 
    def my_method(self):
        """The method's docstring"""
 
 
def my_function():
    """The function's docstring"""

The following is an interactive session showing how the docstrings may be accessed:

>>> import mymodule
>>> help(mymodule)

Assuming this is file mymodule.py then this string, being the
first statement in the file will become the mymodule modules
docstring when the file is imported

>>> help(mymodule.MyClass)
The class's docstring
>>> help(mymodule.MyClass.my_method)
The method's docstring
>>> help(mymodule.my_function)
The function's docstring
>>> 

Content of Python docstrings

one-linemulti-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.
If the stand-alone script uses another module for handling options, such as the argparse module, then option information is moved from the docstring to the modules utilities.

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 of a function or method is a phrase ending in a period. It prescribes the function or method's effect as a command ("Do this", "Return that"), not as a description; e.g. don't write "Returns the pathname ...". A multiline-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.

Tools using docstrings

• cobra -doc (Cobra)
• doctest (Python)
• Epydoc (Python)
• Pydoc (Python)
• Sphinx (Python)

See also

• Literate programming – alternative code commenting paradigm
• Plain Old Documentation – Perl documentation

References

1. ^ Function definition with docstring in Clojure

External links

• Python Docstrings at Epydoc's Sourceforge page
• Documentation in GNU Emacs Lisp
• Section from the doxygen documentation about Python docstrings