Documentación de funciones

Anotación de tipos

La anotación de tipos en Python (type hints) es una forma de especificar los tipos de datos que se espera que tengan los parámetros de una función y el tipo de dato que la función devolverá. Aunque estas anotaciones no son obligatorias y Python no las impone en tiempo de ejecución (Python sigue siendo tipado dinámico), son útiles para la documentación, la comprensión del código y el uso de herramientas de análisis estático como mypy que pueden verificar si los tipos están siendo usados correctamente.

Las anotaciones de tipos se hacen usando la siguiente sintaxis:

• Parámetros de una función: Para anotar el tipo de un parámetro, se coloca dos puntos : después del nombre del parámetro, seguido por el tipo.
• Valor de retorno: Para anotar el tipo de retorno, se utiliza una flecha -> después de los paréntesis que contienen los parámetros, seguida por el tipo de retorno esperado.

def sumar(a: int, b: int) -> int:
    return a + b

• a: int indica que el parámetro a debería ser un entero (int).
• b: int indica que el parámetro b también debería ser un entero.
• -> int indica que la función devolverá un entero.

DocString

Un DocString es una cadena de texto que se encuentra en la parte superior de una función (o también en una clase, método o módulo) que proporciona documentación sobre su propósito y uso. Estos son una forma de documentación en línea y se utilizan para describir la funcionalidad del componente.

La convención más común para escribir los DocStrings es utilizar triples comillas (''' o """) para delimitar el texto.

def funcion_documentada(parametro1, parametro2):
    """
    Esta es la descripción de la función.

    Args:
        parametro1 (int): Descripción del parámetro.
        parametro2 (float): El denominador de la división.

    Returns:
        str: Descripción del valor de retorno.

    """
    # Cuerpo de la función
    return str(parametro1 + parametro2)

En este ejemplo, el DocString está colocado justo debajo de la definición de la función y contiene información sobre el propósito de la función, los parámetros que acepta y el valor que devuelve.

Cuenta con los siguientes componentes:

• Descripción de la función: proporciona una descripción concisa del propósito de la función.
• Sección de parámetros (Args): enumera los parámetros que acepta la función, junto con sus descripciones.
• Sección de valor de retorno (Returns): describe el valor que devuelve la función. Si no devuelve ningún valor, esta sección puede omitirse.
• Otros componentes opcionales: dependiendo de la complejidad, puedes incluir otras secciones como :Raises para las excepciones que puede generar la función, o :Example para proporcionar ejemplos de uso.

Extensión para VSC

Puedes utilizar la extensión "autoDocstring - Python Docstring Generator" para Visual Studio Code para generar automáticamente los DocStrings.

https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring