Docstrings for data?

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!"""

Answer 1

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"

Answer 2

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.

Answer 3

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.