Complete Guide For Python Programming (2015)
DOCUMENTING YOUR CODE
To document a Python object, docstring is used. A docstring is simply a triple-quoted sentence which gives a brief summary of the object. The object can be anything a function, a method, a class, etc.
Anything written in the triple quotes is the function’s docstring, which documents what the function does. A docstring, is the first thing that is defined in a function. Docstring is available at runtime as an attribute of the function. The docstring of a script should be usable as its ‘usage’ message, printed when the script is invoked with incorrect or missing arguments. The docstring is a phrase ending in a period. It describes the function’s effect as a command.
In docstring for a module classes, exceptions and functions that are exported by the module are listed. The docstring for a function or method summarize its behavior and document its arguments, return value(s), side effects and exceptions raised. The docstring for a class summarize its behavior and list the public methods and instance variables. Individual methods should be documented by their own docstring.
You can add a docstring to a function, class, or module by adding a string as the first indented statement.
"""Example of using documentation strings."""
An example class.
Call spam to get bacon.
"""Prints the argument given."""