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

score 4 · Answer 1 · answered Aug 28 '09 at 15:04

4

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.

answered Aug 28 '09 at 15:04

u0b34a0f6ae

48,117
14
92
101

score 1 · Accepted Answer · answered Aug 28 '09 at 15:03

1

Change it into a property method.

answered Aug 28 '09 at 15:03

aehlke

15,225
5
36
45

1

I wonder about this, since then you have to create explicit getter, setter and deleter (I want all three), only to have it behave normally. Is there a way to set default methods for these that simply wrap a class attribute? – u0b34a0f6ae Aug 28 '09 at 15:05

score 0 · Answer 3 · answered Aug 28 '09 at 15:53

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 = ...

in my case attribute has public visibility - that is why help(tagDataMap) is what I want to get — Dewfy, Aug 28 '09 at 16:01

Documenting class attribute

3 Answers3