ejemplo - python create documentation

¿Cómo escribir docstrings significativos?

Question

¿Qué, en tu opinión es una cadena documental significativa? ¿Qué esperas para ser descrito allí?

Por ejemplo, considere el __init__ esta clase 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
    """

¿Encuentras esto significativo? Publique sus ejemplos buenos / malos para que todos lo sepan (y una respuesta general para que pueda aceptarse).

Answer 1

¿Qué debería ir allí?

Todo lo que no se puede decir de la firma del método. En este caso, el único bit útil es: displayName: si está vacío, se configurará como nombre de campo.

Answer 2

De la PEP 8 :

Las convenciones para escribir cadenas de buena documentación (también conocidas como "cadenas de documentos") se inmortalizan en PEP 257 .

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

Answer 3

Echa un vistazo a las cadenas de documentación de Numpy para obtener buenos ejemplos (p. Ej., Http://github.com/numpy/numpy/blob/master/numpy/core/numeric.py).

Las cadenas de documentación 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 4

El propósito general de agregar la cadena de documentos agregada al 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 el futuro desarrollador.

Answer 5

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

Es posible que también 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 obtener un ejemplo, consulte, por ejemplo, repoze.bfg que utiliza este extenso ( archivo de ejemplo , ejemplo de documentación ).

Otra cosa que uno puede poner en docstrings es también doctests . Esto podría tener sentido esp. para las cadenas de documentación del módulo o la clase, ya que también puede mostrar de esa manera cómo usarlo y tener este comprobable al mismo tiempo.

Answer 6

Las cosas más sorprendentes 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 su documentación es un doctest .

Answer 7

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 de borde). 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 algunos detalles 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.