Строки документации для данных?

Question

Есть ли способ описать данные модуля аналогично тому, как строка документации описывает модуль или функцию?

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

Answer 1

Насколько мне известно, невозможно присвоить строки документов элементам данных модуля.

PEP 224 предлагает эту функцию, но PEP был отклонен.

Я предлагаю вам задокументировать элементы данных модуля в строке документации модуля:

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

module.data: contains the word "spam"

"""

data = "spam"

Answer 2

IT является возможно документировать данные модуля с использованием эпидок синтаксис.Epydoc - один из наиболее часто используемых инструментов документирования для Python.

Синтаксис для документирования следующий #: над строкой инициализации переменной, например, так:

# module.py:

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

Теперь, когда вы создаете свою документацию, data будет описана как переменная модуля с заданным описанием и типом str.Вы можете опустить @type линия.

Answer 3

Как объясняет codeape, невозможно документировать общие элементы данных.

Однако можно задокументировать 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''')

Это, очевидно, даст строку документации для атрибута foo .