These are strings that appear right after the definition of a function, method, class or module.
It is enclosed in triple quotes, either single or double quotes, and provides a concise description of the object’s purpose, arguments, return values, and any other relevant details.
def some_function(argument1):
"""
Summary or Description of the some_function
Parameters:
argument1 (int): Description of arg1
"""
return argument1
print(some_function._doc_)
Another example:
def multiply(a, b):
"""
Multiply two numbers together.
Args:
a (float): First number to be multiplied.
b (float): Second number to be multiplied.
Returns:
float: Product of a and b.
"""
return a * b
Types of Docstrings formats
Google-style docstrings: This format uses a specific syntax to provide information about function parameters, return types, and other details. It is commonly used in large projects and follows the convention established by Google.
Numpy-style docstrings: This format is similar to Google-style docstrings but includes additional details about array shapes, data types, and other numerical details.
reStructuredText (RST) docstrings: This format is a markup language used for formatting plain text documents. It is often used in Python documentation and can be used to generate HTML or PDF documents from docstrings.
Epytext-style docstrings: This format uses a plain text format to describe the function, its arguments, and its return values. It is less popular than other formats, but still used by some developers.
The choice of format depends on personal preference and project requirements. It is important to be consistent in the use of docstring formats within a project to ensure clear and easy-to-read documentation.
Python built-in docstrings
All the built-in functions, classes, methods have the actual human description attached to it. You can access it in one of three ways.
pydoc
The help function in python
The _doc_attribute
Generating documentation by using pydoc
The pydoc module automatically generates documentation from Python modules. The documentation can be presented as pages of text on the console, served to a web browser, or saved to HTML files.