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:

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__)

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.