Докстоны для данных?

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

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

Ответы

Ответ 1

Насколько я знаю, невозможно назначить docstrings членам данных модуля.

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

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

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

module.data: contains the word "spam"

"""

data = "spam"

Ответ 2

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

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

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

Ответ 3

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

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

# module.py:

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

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