We use
Numpy style docstrings to document our code.
Docstrings describe functionalities and parameters of the subsequent code and are enclosed in triple quotes (
"""...""").
They are typically placed at the beginning of the module, class, function, or method they describe. Here is the example of Numpy style docstrings for functions:
def my_function (input1, input2):
"""This functions does ...
Parameters
----------
input_1 : type
Description of the parameter `input_1`
input_2 : type
Description of the parameter `input_2`
Returns
-------
output: int
Description of the variable `output`
"""
# function body
return output
The documentation is between the header and the body, and it contains at least the following sections:
-
Description: An explanation of what the function does
-
Parameters: A description of each parameter the function accepts, including name, data type, definition, and default values
-
Returns: A description of the values returned by the function, including name, data type, definition, and any special cases
You can find a complete description of Numpy style docstrings on
the Numpy website
