Pergunta
Existe uma maneira para descrever os dados do módulo de forma similar que uma docstring descreve um módulo ou um funcion?
class MyClass(object):
def my_function():
"""This docstring works!"""
return True
my_list = []
"""This docstring does not work!"""
Solução
A meu conhecimento, não é possível docstrings atribuir a membros de dados do módulo.
PEP 224 sugere esse recurso, mas o PEP foi rejeitada.
Eu sugiro que você documentar os membros de dados de um módulo na docstring do módulo:
# module.py:
"""About the module.
module.data: contains the word "spam"
"""
data = "spam"
Outras dicas
é possível fazer documentação dos dados do módulo, com o uso do epydoc sintaxe. Epydoc é uma das ferramentas de documentação mais utilizados para Python.
A sintaxe para documentação é #:
acima da linha de inicialização de variáveis, como este:
# module.py:
#: Very important data.
#: Use with caution.
#: @type: C{str}
data = "important data"
Agora, quando você gerar sua documentação, data
será descrita como variável módulo com dada descrição e tipo str
. Você pode omitir a linha @type
.
Como codeape explica, não é possível documentar os membros de dados gerais.
No entanto, é possível membros de dados property
documentos:
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''')
Isto lhe dará uma docstring ao atributo foo
, obviamente.