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 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."""
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.