python - name - Docstrings para datos?

python package name

Question

¿Hay alguna manera de describir los datos del módulo de manera similar que una docstring describe un módulo o una función?

class MyClass(object):
def my_function():
"""This docstring works!"""
return True
my_list = []
"""This docstring does not work!"""

Answer 1

Como lo explica codeape, no es posible documentar los miembros de datos generales.

Sin embargo, es posible documentar property miembros de datos de property :

class Foo:
def get_foo(self): ...
def set_foo(self, val): ...
def del_foo(self): ...
foo = property(get_foo, set_foo, del_foo, ''''''Doc string here'''''')

Esto dará una docstring al atributo foo , obviamente.

Answer 2

Es posible hacer la documentación de los datos del módulo, con el uso de la sintaxis epydoc . Epydoc es una de las herramientas de documentación más utilizadas para Python.

La sintaxis para la documentación es #: arriba de la línea de inicialización de la variable, como esta:

# module.py:
#: Very important data.
#: Use with caution.
#: @type: C{str}
data = "important data"

Ahora cuando genere su documentación, los data se describirán como variables de módulo con la descripción dada y tipo str . Puede omitir la línea @type .

Answer 3

Que yo sepa, no es posible asignar documentos a los miembros de datos del módulo.

PEP 224 sugiere esta característica, pero el PEP fue rechazado.

Sugiero que documentes los miembros de datos de un módulo en el docstring del módulo:

# module.py:
"""About the module.
module.data: contains the word "spam"
"""
data = "spam"