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

5 minutos de lectura

Ok, entonces he leído ambos PEP 8 y PEP 257, y he escrito muchas cadenas de documentación para funciones y clases, pero no estoy seguro de lo que debe ir en una cadena de documentación del módulo. 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 derechos de autor, etc. ¿Alguien tiene un ejemplo de cómo debería ser una buena cadena de documentación de Python? ser estructurado?

avatar de usuario
alex martelli

Piensa en alguien haciendo help(yourmodule) a la indicación del intérprete interactivo: ¿qué es lo que desear ¿saber? (Otros métodos de extracción y visualización de la información son más o menos equivalentes a help en términos de cantidad de información). Así que si tienes en x.py:

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

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

después:

>>> 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 muestro una aquí) ya está incluida en las cadenas de documentación de esos componentes; la propia cadena de documentación del módulo debe describirlos muy resumidamente (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 las clases idealmente deberían tener ejemplos documentados en sus cadenas de documentación).

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

  • Entonces, ¿es costumbre incluir autor, derechos de autor, etc. en los comentarios en la parte superior de un módulo?

    usuario297250

    1 de abril de 2010 a las 0:16


  • @ 007brendan, es una práctica bastante común, sí.

    – Alex Martelli

    1 de abril de 2010 a las 0:41

  • @IfLoop dudo que haya más usuarios que usen el help() método en el intérprete que los usuarios que simplemente leen el código.

    – confundido00

    18 de diciembre de 2014 a las 11:24

  • Tenga en cuenta que lo más importante para documentar es por qué. Documentar lo que hace algo es el trabajo de un código bien escrito. Documentar el porqué es el trabajo de la documentación.

    – Erik Aronesty

    3 sep 2019 a las 12:45

  • @ErikAronesty No estoy seguro de entender bien qué significa “documentar por qué”. ¿Tendría alguna documentación que explique el concepto y ejemplos de tales prácticas?

    – número de usuario

    9 oct 2020 a las 8:57

avatar de usuario
remi

Para citar el especificaciones:

La cadena de documentación de un guion
(un programa independiente) debe poder usarse como su mensaje de “uso”, impreso cuando se invoca el script con argumentos incorrectos o faltantes (o quizás con una opción “-h”, para “ayuda”). Dicha cadena de documentación 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 usuario nuevo 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 para 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 una. (Estos resúmenes generalmente brindan menos detalles que la línea de resumen en la cadena de documentación del objeto). La cadena de documentación de un paquete (es decir, la cadena de documentación de la cadena de documentación del paquete) __init__.py module) también debe enumerar los módulos y subpaquetes exportados por el paquete.

La cadena de documentación para un clase
debe resumir su comportamiento y enumerar los métodos públicos y las variables de instancia. Si la clase está destinada a ser subclase y tiene una interfaz adicional para subclases, esta interfaz debe enumerarse 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 estar documentados por su propia cadena de documentación.

La cadena de documentación de un 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 (“Haz esto”, “Devuelve eso”), no como una descripción; por ejemplo, no escriba “Devuelve la ruta de acceso…”. Una cadena de documentos de varias líneas para una función o método debe resumir su comportamiento y documentar sus argumentos, valores devueltos, efectos secundarios, excepciones planteadas y restricciones sobre cuándo se puede llamar (todo si corresponde). Deben indicarse los argumentos opcionales. Debe documentarse si los argumentos de palabras clave son parte de la interfaz.

¿Ha sido útil esta solución?

Esta web utiliza cookies propias y de terceros para su correcto funcionamiento y para fines analíticos y para mostrarte publicidad relacionada con sus preferencias en base a un perfil elaborado a partir de tus hábitos de navegación. Al hacer clic en el botón Aceptar, acepta el uso de estas tecnologías y el procesamiento de tus datos para estos propósitos. Configurar y más información
Privacidad