Documenting Python code with Doctstring

4-minute read
Python
docstrings

It is important for a project to have a documentation on methods, classes and modules is one step to enhance quality on it. Not to confuse “block comments” (using #) with docstring comments.

Next developers generation will be thankfully with your graceful documentation (or not, but you must write it anyway)

I’ve started using this plugin for vscode: Python Docstring Generator(njpwerner.autodocstring) with snippets for docstrings, but also Pycharm generates docstring automatically.

Documenting stuffs let comunicate the purpose and usage (and in some cases test) our artifacts for the next developer generation, also yourself in the future, who needs to fix or just understand what are you thinking when you developed these lines…

In python, docstring are simple as:

Document a method

def method(var1: TypeVar1) -> TypeRes :
    """ Single description of purpose """

Document a package

# in __init__.py file
""" Single description of purpose """

Note: just the same for a module

Where

Docstring could be read with the method __doc__ of any artifact, also we could use builtin help() to read full documentation in an standard format.

>>> print(math.__doc__)
This module is always available.  It provides access to the
mathematical functions defined by the C standard.

How-to

PEP257 standarize conventions related to docstring writing in python code.

There are two main conventions: one-line and multi-line docstring

one-line

It is just one line (as its name :) ). This line describes the artifact (method, module or package) as a command, such: “Return the sum of a list of numbers”, “Do a binary search”, and so on.

multi-line

This docstring is recommended due to its long-nature.

This documentations should show:

  • single description at first line
  • blank line
  • description of a script:
    • usage message & quick reference (such cli programs)
    • arguments and a description (such: --param : explanation)
  • description of a module
    • list classes of its
    • exceptions
    • functions
>>> print(pickle.__doc__)
Create portable serialized representations of Python objects.

See module copyreg for a mechanism for registering custom picklers.
See module pickletools source for extensive comments.

Classes:

    Pickler
    Unpickler

Functions:

    dump(object, file)
    dumps(object) -> string
    load(file) -> object
    loads(string) -> object

Misc variables:

    __version__
    format_version
    compatible_formats
  • description of a package:
    • same as module, adding modules exported
  • description of a function
    • summarize of its behavior
    • arguments and optional arguments
    • return value
    • optional: side effects
    • possible exceptions it may raise
    • restrictions
def fun(p:int, s: str, d:float=20, *args, **kwards) -> bool:
    """[summary]

    Args:
        p (int): [description]
        s (str): [description]
        d (float, optional): [description]. Defaults to 20.

    Returns:
        bool: [description]
    """
    pass
  • description of a class
>>> print(pd.DataFrame.__doc__)

    Two-dimensional, size-mutable, potentially heterogeneous tabular data.

    ....

    Parameters
    ----------
     ...

    See Also
    --------
    ....

    Examples
    --------
    ....

Formats

Ok, I didn’t show up just one format… Which is the correct one? All of them. PEP257 doesn’t explain the format (see also PEP 287), so exists several conventions, but most common are (I took these bullets from daouzli’s post):

  • reStructuredText, probably the most popular for Python docstrings format, with several forms also and that is mainly used in conjonction with Sphinx. Note that this format is used for the Python documentation.
  • Epytext (Javadoc based), that was used years ago for Python but can still be found
  • Google style, that can take several forms
  • Numpydoc, looks like Google docs, used for the numpy related projects (but not only)

What are the purpose of these formats? Some tools could read these information and generate auto-html-documentation, such swagger for rest-apis. The most popular in python-world is Sphinx, it converts reStructured text into HTML, PDF, LaTeX and manuals

References

comments powered by Disqus