¿Cómo escribir cadenas de documentos significativas?

Question

¿Qué, en su opinión, es una cadena de documentos significativa? ¿Qué esperas que se describa allí?

Por ejemplo, considere la __init__ de esta clase de Python:

def __init__(self, name, value, displayName=None, matchingRule="strict"):
    """
    name - field name
    value - field value
    displayName - nice display name, if empty will be set to field name
    matchingRule - I have no idea what this does, set to strict by default
    """

¿Le parece significativo? Publique sus ejemplos buenos / malos para que todos lo sepan (y una respuesta general para que pueda ser aceptado).

Answer 1

Estoy de acuerdo con "Todo lo que no se puede distinguir de la firma del método". También podría significar explicar qué devuelve un método / función.

También es posible que desee utilizar Sphinx (y la sintaxis reStructuredText) para fines de documentación dentro de sus cadenas de documentos. De esa manera, puede incluir esto en su documentación fácilmente. Para ver un ejemplo, consulte, p. repoze.bfg que usa esto ampliamente ( archivo de ejemplo , ejemplo de documentación ).

Otra cosa que se puede poner en las cadenas de documentos es también doctests . Esto podría tener sentido especialmente. para cadenas de documentos de módulo o clase, ya que también puede mostrar de esa manera cómo usarlo y hacer que esto sea comprobable al mismo tiempo.

Answer 2

De PEP 8 :

  

Convenciones para escribir buenas cadenas de documentación (a.k.a.   " docstrings ") están inmortalizados en PEP 257 .

     

  
• Escribir cadenas de documentos para todos los módulos públicos, funciones, clases y métodos. Las cadenas de documentos no son necesarias para métodos no públicos, pero usted   debería tener un comentario que describa lo que hace el método. Esta   el comentario debe aparecer después de "def" línea.
  
• PEP 257 describe buenas convenciones de docstring. Tenga en cuenta que lo más importante, el " " " que termina una cadena de documentos multilínea debe estar en un   línea por sí misma, y ??preferiblemente precedida por una línea en blanco.
  
• Para las cadenas de documentos de un revestimiento, está bien mantener el cierre " " " en la misma línea.
  

Answer 3

Qué debería ir allí:

Cualquier cosa que no puedas distinguir de la firma del método. En este caso, el único bit útil es: displayName: si está vacío, se establecerá en el nombre del campo.

Answer 4

Consulte las cadenas de documentación de numpy para obtener buenos ejemplos (por ejemplo, http: / /github.com/numpy/numpy/blob/master/numpy/core/numeric.py ).

Las cadenas de documentos se dividen en varias secciones y se ven así:

Compute the sum of the elements of a list.

Parameters
----------
foo: sequence of ints
   The list of integers to sum up.

Returns
-------
res: int
   sum of elements of foo

See also
--------
cumsum:  compute cumulative sum of elemenents

Answer 5

Las cosas más llamativas que se me ocurren para incluir en una cadena de documentos son las cosas que no son obvias. Por lo general, esto incluye información de tipo o requisitos de capacidad, por ejemplo. " Requiere un objeto similar a un archivo " ;. En algunos casos, esto será evidente a partir de la firma, no así en otros casos.

Otra cosa útil que puede poner en sus cadenas de documentos es un doctest .

Answer 6

Me gusta usar la documentación para describir con el mayor detalle posible lo que hace la función, especialmente el comportamiento en casos de esquina (también conocidos como casos extremos). Idealmente, un programador que use la función nunca debería tener que mirar el código fuente; en la práctica, eso significa que cada vez que otro programador tenga que mirar el código fuente para descubrir algún detalle de cómo funciona la función, ese detalle probablemente debería haber sido mencionado en la documentación. Como dijo Freddy, cualquier cosa que no agregue ningún detalle a la firma del método probablemente no debería estar en una cadena de documentación.

Answer 7

El propósito general de agregar la adición de una cadena de documentos en el inicio de la función es describir la función, lo que hace, lo que devolvería y la descripción de los parámetros. Puede agregar detalles de implementación si es necesario. Incluso puede agregar detalles sobre el autor que escribió el código para futuros desarrolladores.