How to Document with Docstrings in Python

In Python, function documentation is crucial for understanding and efficiently using code.

Docstrings (short for “documentation strings”) are text strings placed at the beginning of a module, class, method, or function definition to describe its purpose and how it should be used.

They are defined using triple quotes (""" or ''') and can be accessed via the __doc__ attribute.

Syntax of Docstrings

The basic structure of a docstring for functions includes:

def function_name(parameters):
    """
    Description of the function

    Parameters:
    - parameter1: description of the parameter
    - parameter2: description of the parameter

    Returns:
    - return_type: description of the return type
    """
    # Function body

1. A brief description of the function.
2. Description of the parameters (if any).
3. Description of the return value (if any).
4. Information about exceptions (if any).

It is simply a convention. But it is important to follow it so that Python documentation tools can properly process the docstrings.

Example of a Docstring

Let’s see it with a simple example of what a docstring might look like for a function that calculates the average of a series of numbers:

def calculate_average(list):
    '''
    This function calculates the average of a list of numbers.

    Args:
        list (list): A list of numbers to calculate the average.

    Returns:
        float: The average of the numbers in the list.
    '''
    total = sum(list)
    average = total / len(list)
    return average

In this example, the docstring describes the purpose of the calculate_average function, its argument (list), and what it returns (float).

Types of Docstrings

In Python, there are several types of docstrings used for different purposes. Some of the most common types are:

• Function Docstrings: Describe the purpose of a function, its arguments, and what it returns. This is the one we saw in the previous example.

• Module Docstrings: Describe the module in general and are placed at the beginning of the module file.

"""
Mathematical operations module.

This module provides basic functions for performing mathematical operations such as addition, subtraction, multiplication, and division.

Functions:
- add(a, b): Returns the sum of a and b.
- subtract(a, b): Returns the result of subtracting b from a.
- multiply(a, b): Returns the product of a and b.
- divide(a, b): Returns the division of a by b.
"""

def add(a, b):
## ...
## here the rest of the module code

Class Docstrings: Describe the purpose of a class, its methods, and attributes.

class Car:
    """
    Represents a car.
    
    Attributes:
    brand (str): The brand of the car.
    model (str): The model of the car.
    """

## ...
## here the rest of the class code

Accessing Documentation

In Python, it is possible for a function to access its own documentation.

def add(a, b):
    """
    Returns the sum of a and b.
    
    Parameters:
    a (int, float): The first number.
    b (int, float): The second number.
    
    Returns:
    int, float: The sum of a and b.
    """
    return a + b

print(add.__doc__)

Which probably won’t bring anything good. But since you can do it, you can. But don’t do it. 😊

Automatic Documentation Generation

Tools like Sphinx and Doxygen can generate HTML documentation and other formats from docstrings, making it easier to create documentation.