Docstrings

A documentation string (docstring) is a string that describes a module, function, class, or method definition. A docstring should include the following components:

• A short summary
• An optional extended summary
• Parameters
• Attributes - required by class __init__
• Methods - maps to exposed functions for class
• Returns (or Yields for generators)
• Raises - if required
• Notes (optional)
• References (optional)
• Examples (optional)

Correct

class Foo(object):
    """Short description of the class

    Optional longer description of the class

    Attributes
    ----------
    x : float
        The X coordinate
    y : float
        The Y coordinate

    Methods
    -------
    bar(var1: list, var2: int, var3: str ='hi', *args, **kwargs)
        Some small description of bar
    """

    def __init__(self, x: float, y: float):
        self.x = x
        self.y = y

    def bar(var1: list, var2: int, var3: str = "hi", *args, **kwargs):
        """Short summary of the code

         Several sentences providing an extended description. Refer to
         variables using back-ticks, e.g. `var`.

         Parameters
         ----------
         var1 : array_like
             Array_like means all those objects -- lists, nested lists, etc. --
             that can be converted to an array.  We can also refer to
             variables like `var1`.
         var2 : int
             The type above can either refer to an actual Python type
             (e.g. ``int``), or describe the type of the variable in more
             detail, e.g. ``(N,) ndarray`` or ``array_like``.
         var3: {'hi', 'ho'}, optional
             Choices in brackets, default first when optional.
         *args : iterable
             Other arguments.
         **kwargs : dict
             Keyword arguments.

         Returns
         -------
         describe : type
             Explanation of return value named `describe`.
         out : type
             Explanation of `out`.

         Raises
         ------
         BadException
             Because you shouldn't have done that.

         Notes
         -----
         Notes about the implementation algorithm (if needed).

         This can have multiple paragraphs.

         You may include some math:

         .. math:: X(e^{j\omega } ) = x(n)e^{ - j\omega n}

         And even use a Greek symbol like :math:`\omega` inline.

        References
        ----------
         Cite the relevant literature, e.g. [1]_.  You may also cite these
         references in the notes section above.

         .. [1] O. McNoleg, "The integration of GIS, remote sensing,
           expert systems and adaptive co-kriging for environmental habitat
           modelling of the Highland Haggis using object-oriented, fuzzy-logic
           and neural-network techniques," Computers & Geosciences, vol. 22,
           pp. 585-588, 1996.

         Examples
         --------
         These are written in doctest format, and should illustrate how to
         use the function.

         >>> a = [1, 2, 3]
         >>> print([x + 3 for x in a])
         [4, 5, 6]
        """

    pass