Docstrings para datos?

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

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

PEP 224 sugiere esta característica, pero se rechazó el PEP.

Sugiero a documentar los miembros de datos de un módulo en cadena de documentación del módulo:

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

module.data: contains the word "spam" 

""" 

data = "spam" 

Answer 2

Se es posible hacer la 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 #: por encima de la línea de inicialización de variables, como esto:

# module.py: 

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

Ahora cuando se genera la 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 se explica en codeape, no es posible documentar los miembros de datos generales.

Sin embargo, es posible documentar property miembros de datos:

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 para el atributo foo, obviamente.