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

Question

Ok, he leído PEP 8 y PEP 257, y he escrito muchas cadenas de documentos para funciones y clases, pero estoy un poco inseguro acerca de lo que debe 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

Piense en alguien que hace help(yourmodule) en el intérprete interactivo - ¿qué quieren quiere saber para saber? (Otros métodos para extraer y mostrar la información son aproximadamente equivalentes a help en términos de cantidad de información). Así que si usted tiene en x.py:

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

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

a continuación:

>>> import x; help(x) 

espectáculos:

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 se ve, la información detallada sobre las clases (y funciones también, aunque' m no muestra uno aquí) ya está incluido en los 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 los derechos de autor/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.

Answer 2

citar el specifications:

La cadena de documentación de un (un programa independiente) guión debe ser utilizable como su mensaje de "uso", impreso cuando el script se invoca con incorrecta o falta argumentos (o tal vez con una 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 para un módulo generalmente debe enumerar las clases, excepciones y funciones (y cualesquiera otros objetos) que se exportan por el módulo, 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.

La docstring para 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 un función o método es una frase que termina en un período. Prescribe la función o el efecto del método como un comando ("Hacer esto", "Devolver eso"), no como una descripción; p.ej. no escribir "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.