[SciPy-dev] Documenting classes

[Stéfan van der Walt]

2008/6/16 Robert Kern <robert.kern at gmail.com>:
> Not per se, but most of the general outline of the function template
> applies. Ignore Returns. I think I like having the __init__
> constructor Parameters in the class docstring, but I will defer to
> Stéfan's proclamation.

I do, too.  `__init__` is exposed to users as ClassName(), so that is
where they will look for the docstring.   We are not bound religiously
to PEP-257, which suggests:

"""
The class constructor should be documented in the docstring for its
__init__ method. Individual methods should be documented by their own
docstring.
"""

> I recommend adding a section like Parameters.
>
>  Attributes
>  ----------
>  x : float
>      The X coordinate.
>  y : float
>      The Y coordinate.

Let's do that.  Unfortunately, Python does not pick up docstrings of the form:

"""My variable description."""
my_var = 3

so we'll have to go with an Attributes section.  On the other hand,
methods can be inspected (i.e. TAB-completion in IPython, 'help' or
'dir' in the raw shell), so we don't need to list the methods, as
suggested in the PEP:

"The docstring for a class should summarize its behavior and list the
public methods and instance variables."

I have updated the documentation guidelines:

http://projects.scipy.org/scipy/numpy/wiki/CodingStyleGuidelines#documenting-classes

Cheers
Stéfan