fbpx

Docstrings

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

  1. 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.

  2. Numpy-style docstrings: This format is similar to Google-style docstrings but includes additional details about array shapes, data types, and other numerical details.

  3. 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.

  4. 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. 

python -m pydoc
python -m pydoc math
python -m pydoc random
python -m pydoc tuple
python -m pydoc pow
python -m pydoc -k <keyword>
Python -m pydoc -p 1234
Loading...