Documenting class attribute

Question

Following sample is taken from "Dive into python" book.

class MP3FileInfo(FileInfo):
    "store ID3v1.0 MP3 tags"
    tagDataMap = ...

This sample shows documenting the MP3FileInfo, but how can I add help to MP3FileInfo. tagDataMap

Answer 1

Change it into a property method.

Answer 2

The PEP 224 on attribute docstrings was rejected (long time ago), so this is a problem for me as well, sometimes I don't know to choose a class attribute or an instance property -- the second can have a docstring.

Answer 3

Do it like this:

class MP3FileInfo(FileInfo):
    """Store ID3v1.0 MP3 tags."""

    @property 
    def tagDataMap(self):
        """This function computes map of tags.

        The amount of work necessary to compute is quite large, therefore
        we memoize the result.

        """
        ...

Note though you really shouldn't make a separate docstring if the attribute has only a one-line description. Instead, use

class MP3FileInfo(FileInfo):
    """Store ID3v1.0 MP3 tags.

    Here are the attributes:
        tagDataMap -- contains a map of tags

    """

    tagDataMap = ...