Strings de documentación de Python

Las strings de documentación de Python (o docstrings) proporcionan una manera conveniente de asociar documentación con módulos, funciones, clases y métodos de Python.

Se especifica en el código fuente que se usa, como un comentario, para documentar un segmento específico de código. A diferencia de los comentarios de código fuente convencionales, la string de documentación debe describir qué hace la función, no cómo.

¿Cómo debería ser una string de documentos?

• La línea de la string de documentos debe comenzar con una letra mayúscula y terminar con un punto.
• La primera línea debe ser una breve descripción.
• Si hay más líneas en la string de documentación, la segunda línea debe estar en blanco, separando visualmente el resumen del resto de la descripción.
• Las siguientes líneas deben ser uno o más párrafos que describan las convenciones de llamada del objeto, sus efectos secundarios, etc.

Declaración de Docstrings: Las docstrings se declaran usando ”’comillas simples triples”’ o “””comillas dobles triples””” justo debajo de la declaración de clase, método o función. Todas las funciones deben tener una string de documentación.

Acceder a Docstrings: Se puede acceder a las docstrings usando el método __doc__ del objeto o usando la función de ayuda.
Los siguientes ejemplos muestran cómo declarar y acceder a una string de documentos.

Ejemplo 1: uso de comillas simples triples

def my_function():
    '''Demonstrates triple double quotes
    docstrings and does nothing really.'''
   
    return None
  
print("Using __doc__:")
print(my_function.__doc__)
  
print("Using help:")
help(my_function)

Producción:

Using __doc__:
Demonstrates triple double quotes
    docstrings and does nothing really.
Using help:
Help on function my_function in module __main__:

my_function()
    Demonstrates triple double quotes
    docstrings and does nothing really.

Ejemplo 2: uso de comillas dobles triples

def my_function():
    """Demonstrates triple double quotes
    docstrings and does nothing really."""
   
    return None
  
print("Using __doc__:")
print(my_function.__doc__)
  
print("Using help:")
help(my_function)

Producción:

Using __doc__:
Demonstrates triple double quotes
    docstrings and does nothing really.
Using help:
Help on function my_function in module __main__:

my_function()
    Demonstrates triple double quotes
    docstrings and does nothing really.

Strings de documentos de una línea

Como sugiere el nombre, las strings de documentos de una línea caben en una línea. Se utilizan en casos obvios. Las comillas de cierre están en la misma línea que las comillas de apertura. Esto se ve mejor para las frases de una sola línea.
Por ejemplo:

def power(a, b):
    """Returns arg1 raised to power arg2."""
   
    return a**b
  
print(power.__doc__)

Producción:

Returns arg1 raised to power arg2.

Docstrings multilínea

Las strings de documentos de varias líneas constan de una línea de resumen, como una string de documentos de una línea, seguida de una línea en blanco, seguida de una descripción más elaborada. La línea de resumen puede estar en la misma línea que las comillas de apertura o en la línea siguiente.
El siguiente ejemplo muestra una string de documentación de varias líneas.

def my_function(arg1):
    """
    Summary line.
  
    Extended description of function.
  
    Parameters:
    arg1 (int): Description of arg1
  
    Returns:
    int: Description of return value
  
    """
  
    return arg1
  
print(my_function.__doc__)

Producción:

    Summary line.
    Extended description of function.
    Parameters:
    arg1 (int): Description of arg1

    Returns:
    int: Description of return value

Sangría en Docstrings

Toda la string de documentación tiene la misma sangría que las comillas en su primera línea. Las herramientas de procesamiento de strings de documentación eliminarán una cantidad uniforme de sangría de la segunda y posteriores líneas de la string de documentación, igual a la sangría mínima de todas las líneas que no estén en blanco después de la primera línea. Cualquier sangría en la primera línea de la string de documentación (es decir, hasta la primera línea nueva) es insignificante y se elimina. Se conserva la sangría relativa de las líneas posteriores en la string de documentación.

Strings de documentos en las clases

Tomemos un ejemplo para mostrar cómo escribir strings de documentos para una clase y sus métodos. ayuda se utiliza para acceder a la string de documentación.

class ComplexNumber:
    """
    This is a class for mathematical operations on complex numbers.
      
    Attributes:
        real (int): The real part of complex number.
        imag (int): The imaginary part of complex number.
    """
  
    def __init__(self, real, imag):
        """
        The constructor for ComplexNumber class.
  
        Parameters:
           real (int): The real part of complex number.
           imag (int): The imaginary part of complex number.   
        """
  
    def add(self, num):
        """
        The function to add two Complex Numbers.
  
        Parameters:
            num (ComplexNumber): The complex number to be added.
          
        Returns:
            ComplexNumber: A complex number which contains the sum.
        """
  
        re = self.real + num.real
        im = self.imag + num.imag
  
        return ComplexNumber(re, im)
  
help(ComplexNumber)  # to access Class docstring
help(ComplexNumber.add)  # to access method's docstring

Producción:

Help on class ComplexNumber in module __main__:

class ComplexNumber
 |  This is a class for mathematical operations on complex numbers.
 |  
 |  Attributes:
 |          real (int): The real part of complex number.
 |          imag (int): The imaginary part of complex number.
 |  
 |  Methods defined here:
 |  
 |  __init__(self, real, imag)
 |      The constructor for ComplexNumber class.
 |      
 |      Parameters:
 |      real (int): The real part of complex number.
 |      imag (int): The imaginary part of complex number.
 |  
 |  add(self, num)
 |      The function to add two Complex Numbers.
 |      
 |      Parameters:
 |              num (ComplexNumber): The complex number to be added.
 |      
 |      Returns:
 |              ComplexNumber: A complex number which contains the sum.

Help on method add in module __main__:

add(self, num) unbound __main__.ComplexNumber method
    The function to add two Complex Numbers.
    
    Parameters:
            num (ComplexNumber): The complex number to be added.
    
    Returns:
            ComplexNumber: A complex number which contains the sum.

La diferencia entre los comentarios de Python y las strings de documentación

Todos deben tener una idea sobre las strings de documentación de Python, pero ¿alguna vez se han preguntado cuál es la diferencia entre los comentarios de Python y las strings de documentación? Echemos un vistazo a ellos.

Los comentarios de Python son la información útil que proporcionan los desarrolladores para que el lector comprenda el código fuente. Explica la lógica o una parte de ella utilizada en el código. Se escribe usando el #símbolo.

Ejemplo:

# Python program to demonstrate comments
print("GFG")

Producción:

GFG

Mientras que Python Docstrings, como se mencionó anteriormente, proporciona una forma conveniente de asociar documentación con módulos, funciones, clases y métodos de Python.

Este artículo es una contribución de Mayank Agrawal . Si le gusta GeeksforGeeks y le gustaría contribuir, también puede escribir un artículo usando contribuya.geeksforgeeks.org o envíe su artículo por correo a contribuya@geeksforgeeks.org. Vea su artículo que aparece en la página principal de GeeksforGeeks y ayude a otros Geeks.

Escriba comentarios si encuentra algo incorrecto o si desea compartir más información sobre el tema tratado anteriormente.