Cadenas de documentos para datos?

Question

¿Hay alguna manera de describir los datos del módulo de manera similar a como una cadena de documentación 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

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

PEP 224 sugiere esta característica, pero la PEP fue rechazada.

Le sugiero que documente los miembros de datos de un módulo en la cadena de documentación del módulo:

# module.py:
"""About the module.

module.data: contains the word "spam"

"""

data = "spam"

Answer 2

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

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

# module.py:

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

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

Answer 3

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

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

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 le dará una cadena de documentación al atributo foo , obviamente.