Есть ли способ описать данные модуля аналогично тому, как docstring описывает модуль или функцию?
class MyClass(object):
def my_function():
"""This docstring works!"""
return True
my_list = []
"""This docstring does not work!"""
Насколько я знаю, невозможно назначить docstrings членам данных модуля.
PEP 224 предлагает эту функцию, но PEP был отклонен.
Я предлагаю вам документировать элементы данных модуля в модуле docstring:
# module.py:
"""About the module.
module.data: contains the word "spam"
"""
data = "spam"
Как поясняет кодеп, невозможно документировать общие элементы данных.
Однако можно документировать 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, очевидно.
можно сделать документацию по данным модуля, используя синтаксис epydoc. Epydoc является одним из наиболее часто используемых инструментов документации для Python.
Синтаксис для документирования - это #: над строкой инициализации переменной, например:
# module.py:
#: Very important data.
#: Use with caution.
#: @type: C{str}
data = "important data"
Теперь, когда вы создаете свою документацию, data будет описываться как переменная модуля с данным описанием и введите str. Вы можете опустить строку @type.