¿Qué poner en una cadena de documentación del módulo de Python? [cerrado]

Ok, entonces leí tanto PEP 8 como PEP 257 , y escribí muchas cadenas de documentos para funciones y clases, pero estoy un poco inseguro acerca de lo que debería ir en una cadena de documentos de módulo. Supuse 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 derechos de autor, etc. ¿Alguien tiene un ejemplo de cómo debería ser una buena cadena de documentos de Python? ser estructurado?

Piense en alguien que hace help(yourmodule)lo que le pide el intérprete interactivo: ¿qué quiere saber? (Otros métodos de extracción y visualización de la información son aproximadamente equivalentes helpen 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."""

luego:

>>> 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 las funciones también, aunque no estoy mostrando una aquí) ya está incluida en las cadenas de documentos de esos componentes; la propia cadena de documentación del módulo debe describirlos de manera muy sumaria (si es que lo hace) y más bien concentrarse en un resumen conciso de lo que el módulo en su conjunto puede hacer por usted, idealmente con algunos ejemplos documentados (al igual que las funciones y clases idealmente deberían tener ejemplos documentados en sus cadenas de documentos).

No veo cómo los metadatos, como el nombre del autor y los derechos de autor / licencia, ayudan al usuario del módulo, sino que pueden ir en los comentarios, ya que podrían ayudar a alguien a considerar si reutilizar o modificar el módulo.

Para citar las especificaciones :

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

La cadena de documentación de un módulo generalmente debe enumerar las clases, excepciones y funciones (y cualquier otro objeto) que exporta 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 documentación del objeto). La cadena de documentación para un paquete (es decir, la cadena de documentación del __init__.pymódulo del paquete ) también debe enumerar los módulos y subpaquetes exportados por el paquete.

La cadena de documentación 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 subclasificarse y tiene una interfaz adicional para subclases, esta interfaz se debe enumerar por separado (en la cadena de documentación). El constructor de la clase debe documentarse en la cadena de documentación para su __init__método. Los métodos individuales deben documentarse por su propia cadena de documentación.

La cadena de documentos de una función o método es una frase que termina en un punto. Prescribe el efecto de la función o método como un comando ("Hacer esto", "Devolver eso"), no como una descripción; por ejemplo, no escriba "Devuelve el nombre de ruta ...". Una cadena de documentos multilínea para una función o método debe resumir su comportamiento y documentar sus argumentos, valor (es) de retorno, efectos secundarios, excepciones generadas y restricciones sobre cuándo se puede invocar (todo si corresponde). Deben indicarse argumentos opcionales. Debe documentarse si los argumentos de palabras clave son parte de la interfaz.