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

score 15 · Accepted Answer · answered Oct 13 '08 at 12:55

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"

score 11 · Answer 2 · answered Oct 13 '08 at 13:23

11

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.

answered Oct 13 '08 at 13:23

Dzinx

55,586
10
60
78

1

Even though this is cool, I was looking for exactly docstings (since these are the most helpful in the console environment using help builtin). Anyway thanx – Bartosz Radaczyński Oct 13 '08 at 13:43

score 10 · Answer 3 · answered Oct 13 '08 at 22:08

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.

Docstrings for data?

3 Answers3