Python Grammar Note (1): how to make proper code documentation
I am writing this note for record my experience with regard to Python code documentation. The note is based on the following article: Documenting Python Code: A Complete Guide
- How to document Python function?
When writing a Python function, we need follow the following documentation rules controlled by docstring:
- A one-line summary line
- A blank line proceeding the summary
- Any further elaboration for the docstring
- Another blank line
Here is an example:
def gini(arr: np.array) -> float:
"""
This function is used to calculate Gini coefficient. In economics, the Gini coefficient, sometimes called the Gini index or
Gini ratio, is a measure of statistical dispersion intended to represent
the income inequality or wealth inequality within a nation. Here we use it
to represent the inequality of popularization distribution in a certain
country. :param arr: a np.array whose rank is 1
:return: the Gini coefficient whose while is between 0 and 1. The smaller,
the better. It is a float value.
"""
We can use two ways to check the documentation
print(gini.__doc__) or help(gini)