Question
Is there a way to describe the module's data in a similar way that a docstring describes a module or a funcion?
class MyClass(object):
def my_function():
"""This docstring works!"""
return True
my_list = []
"""This docstring does not work!"""
Solution
To my knowledge, it is not possible to assign docstrings to module data members.
PEP 224 suggests this feature, but the PEP was rejected.
I suggest you document the data members of a module in the module's docstring:
# module.py:
"""About the module.
module.data: contains the word "spam"
"""
data = "spam"
OTHER TIPS
It is possible to make documentation of module's data, with use of epydoc syntax. Epydoc is one of the most frequently used documentation tools for Python.
The syntax for documenting is #:
above the variable initialization line, like this:
# module.py:
#: Very important data.
#: Use with caution.
#: @type: C{str}
data = "important data"
Now when you generate your documentation, data
will be described as module variable with given description and type str
. You can omit the @type
line.
As codeape explains, it's not possible to document general data members.
However, it is possible to document property
data members:
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''')
This will give a docstring to the foo
attribute, obviously.