Docstrings para dados?

Question

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!"""

Answer 1

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"

Answer 2

é 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.

Answer 3

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.