Cómo documentar con Docstrings en Python

En Python, docstrings se emplea para generar la documentación de funciones, que es importante para dar instrucciones a otros sobre cómo usar nuestro código.

Las docstrings (abreviatura de “documentation strings”) son cadenas de texto que se colocan al comienzo de una definición de módulo, clase, método o función para describir su propósito y cómo se debe utilizar.

Se definen utilizando triples comillas (""" o ''') y se pueden acceder mediante el atributo __doc__.

Sintaxis de los docstrings

La estructura básica de una docstring para funciones incluye:

def nombre_de_la_funcion(parametros):
    """
    Descripción de la función

    Parámetros:
    - parametro1: descripción del parámetro
    - parametro2: descripción del parámetro

    Retorna:
    - tipo_de_retorno: descripción del tipo de retorno
    """
    # Cuerpo de la función

Generalmente el docstring contendra:

1. Una breve descripción de la función.
2. Descripción de los parámetros (si los hay).
3. Descripción del valor de retorno (si lo hay).
4. Información sobre excepciones (si las hay).

Es principalmente una convención. Pero es importante seguirla para que las herramientas de documentación de Python puedan procesar correctamente los docstrings.

Ejemplo de docstring

Vamos a verlo con un ejemplo sencillo de como podría ser un docstring para una función que calcula el promedio de una serie de números:

def calcular_promedio(lista):
    '''
    Esta función calcula el promedio de una lista de números.

    Args:
        lista (list): Una lista de números para calcular el promedio.

    Returns:
        float: El promedio de los números en la lista.
    '''
    suma = sum(lista)
    promedio = suma / len(lista)
    return promedio

En este ejemplo, la docstring describe el propósito de la función calcular_promedio, sus argumentos (lista) y lo que devuelve (float).

Tipos de Docstrings

En Python, existen varios tipos de docstrings que se utilizan para diferentes propósitos. Algunos de los tipos más comunes son:

• Docstrings de Funciones: Describen el propósito de una función, sus argumentos y lo que devuelve (es el que hemos visto en el ejemplo anterior)

• Docstrings de Módulos: Describen el módulo en general y se colocan al principio del archivo del módulo.

"""
Módulo de operaciones matemáticas.

Este módulo proporciona funciones básicas para realizar operaciones matemáticas como suma, resta, multiplicación y división.

Funciones:
- suma(a, b): Devuelve la suma de a y b.
- resta(a, b): Devuelve la resta de b de a.
- multiplicar(a, b): Devuelve el producto de a y b.
- dividir(a, b): Devuelve la división de a entre b.
"""

def suma(a, b):
## ...
## aqui el resto del código del módulo

Docstrings de Clases: Describen el propósito de una clase, sus métodos y atributos.

class Coche:
    """
    Representa un coche.
    
    Atributos:
    marca (str): La marca del coche.
    modelo (str): El modelo del coche.
    """

## ...
## aqui el resto del código de la clase

Acceso a la documentación

En Python, es posible que una función acceda a su propia documentación, usando la función __doc__

def suma(a, b):
    """
    Devuelve la suma de a y b.
    
    Parámetros:
    a (int, float): El primer número.
    b (int, float): El segundo número.
    
    Devuelve:
    int, float: La suma de a y b.
    """
    return a + b

print(suma.__doc__)

Lo cuál, probablemente no traiga nada bueno. Pero por poderlo hacer, puedes (pero no lo hagas 😊).

Generación Automática de Documentación

Existen herramientas como Sphinx y Doxygen que pueden generar documentación HTML y otros formatos a partir de docstrings.

Esto facilita crear la creación de documentación para librerías o proyectos.