[SciPy-dev] Doc-ing classes and data attributes

[Pierre GM]

On Jun 20, 2009, at 7:23 PM, David Goldsmith wrote:

>
> Ok, a couple follow-up questions: where precisely should  
> documentation of __init__, and the Attributes and Methods sections  
> (when needed) go?  In other words, docstringstandard says, "Use the  
> same sections as outlined [for Functions]," but as Functions don't  
> have __init__, Attributes, or Methods, it is unclear where in the  
> "above" template these new items should go.

My 2c:

* I don't document __init__, but I put a 'Parameters' section in the  
docstring of the class that describes all the input parameters of  
__init__
* Methods could be described in the docstring of the class, under a  
'Methods' entry, but it might be more appropriate to document them  
outside the class.
* Same thing for Attributes: you could have a small list in the  
docstring, but as soon as you start documenting an attribute in  
detail, you'd better have a separate section.

Check http://pytseries.sourceforge.net/core.timeseries.html for an  
example of application.