python3 - missing method docstring

¿Qué poner en un docstring del módulo python?

Question

Ok, entonces he leído tanto PEP 8 como PEP 257 , y he escrito muchas cadenas de documentos para funciones y clases, pero estoy un poco inseguro acerca de lo que debería ir en un módulo de documentos. Pensé que, como mínimo, debería documentar las funciones y clases que exporta el módulo, pero también he visto algunos módulos que enumeran los nombres de los autores, la información de copyright, etc. ¿Alguien tiene un ejemplo de cómo debe ser una buena cadena de python? ser estructurado?

Answer 1

Para citar las specifications :

El docstring de un script (un programa independiente) debe ser utilizable como su mensaje de "uso", impreso cuando el script se invoca con argumentos incorrectos o faltantes (o tal vez con la opción "-h" para "ayuda"). Tal docstring debería documentar la función del script y la sintaxis de la línea de comando, las variables de entorno y los archivos. Los mensajes de uso pueden ser bastante elaborados (varias pantallas llenas) y deben ser suficientes para que un nuevo usuario utilice el comando correctamente, así como una referencia rápida completa a todas las opciones y argumentos para el usuario sofisticado.

El docstring de un módulo generalmente debe enumerar las clases, excepciones y funciones (y cualquier otro objeto) que el módulo exporte, con un resumen de una línea de cada uno. (Estos resúmenes generalmente dan menos detalles que la línea de resumen en la cadena de documentos del objeto). La carpeta docstring para un paquete (es decir, la docstring del módulo __init__.py del paquete) también debe enumerar los módulos y subpaquetes exportados por el paquete.

El docstring de una clase debe resumir su comportamiento y enumerar los métodos públicos y las variables de instancia. Si la clase está destinada a ser subclasificada, y tiene una interfaz adicional para las subclases, esta interfaz se debe enumerar por separado (en la docstring). El constructor de clase debe documentarse en la docstring para su método __init__ . Los métodos individuales deben estar documentados por su propia docstring.

El docstring de una función o método es una frase que termina en un punto. Prescribe la función o el efecto del método como un comando ("Hacer esto", "Devolver eso"), no como una descripción; por ejemplo, no escriba "Devuelve la ruta de acceso ...". Un multilínea-docstring para una función o método debe resumir su comportamiento y documentar sus argumentos, los valores de devolución, los efectos secundarios, las excepciones planteadas y las restricciones sobre cuándo se puede invocar (todo, si corresponde). Se deben indicar los argumentos opcionales. Se debe documentar si los argumentos de palabra clave son parte de la interfaz.

Answer 2

Piense en alguien help(yourmodule) en el prompt del intérprete interactivo: ¿qué es lo que quieren saber? (Otros métodos para extraer y mostrar la información son más o menos equivalentes a la help en términos de cantidad de información). Entonces, si tienes en x.py :

"""This module does blah blah."""

class Blah(object):
  """This class does blah blah."""

entonces:

>>> import x; help(x)

muestra:

Help on module x:

NAME
    x - This module does blah blah.

FILE
    /tmp/x.py

CLASSES
    __builtin__.object
        Blah

    class Blah(__builtin__.object)
     |  This class does blah blah.
     |  
     |  Data and other attributes defined here:
     |  
     |  __dict__ = <dictproxy object>
     |      dictionary for instance variables (if defined)
     |  
     |  __weakref__ = <attribute ''__weakref__'' of ''Blah'' objects>
     |      list of weak references to the object (if defined)

Como puede ver, la información detallada sobre las clases (y funciones también, aunque no la muestro aquí) ya está incluida en las cadenas de documentos de esos componentes; la propia documentación del módulo debe describirlos muy resumidamente (si es que lo hace) y concentrarse en un resumen conciso de lo que el módulo como un todo puede hacer por usted, idealmente con algunos ejemplos documentados (al igual que las funciones y las clases idealmente deberían tener ejemplos comprobados en theit docstrings).

No veo cómo los metadatos, como el nombre del autor y el copyright / licencia, ayudan al usuario del módulo; puede incluir comentarios, ya que podría ayudar a alguien a considerar si reutilizar o modificar el módulo.