Документы для данных?

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

Как объясняет 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, очевидно.

Answer 3

С помощью возможно можно документировать данные модуля с использованием синтаксиса *1003* epydoc . Epydoc - один из наиболее часто используемых инструментов документации для Python.

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

# module.py:

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

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