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

David Goldsmith d_l_goldsmith@yahoo....
Sat Jun 20 18:23:39 CDT 2009


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.  

Also, since __init__ is a method, I assume it should itself be documented like any other method, i.e., w/ a definition, one line desc., multi-line desc., parameters section, etc.  To my mind, to avoid clutter and excessively long docstrings, it seems like it should be documented separately; but then perhaps what is meant is that documenting the class is really documenting its __init__?

Thanks,

DG

--- On Fri, 6/19/09, Stéfan van der Walt <stefan@sun.ac.za> wrote:

> From: Stéfan van der Walt <stefan@sun.ac.za>
> Subject: Re: [SciPy-dev] Doc-ing classes and data attributes
> To: "SciPy Developers List" <scipy-dev@scipy.org>
> Date: Friday, June 19, 2009, 11:19 PM
> Hi David
> 
> 2009/6/20 David Goldsmith <d_l_goldsmith@yahoo.com>:
> > Hi!  The template http://projects.scipy.org/numpy/browser/trunk/doc/example.py#L37
> for documenting things doesn't seem like a very good
> template for documenting objects, e.g., ufunc, and data (as
> opposed to method) attributes of objects, e.g.,
> ndarray.dtype.  Are there other templates for these
> elsewhere?  Thanks!
> 
> Have a look at
> 
> http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines#docstring-standard
> 
> under the section "Documenting Classes".  Is that what
> you're looking for?
> 
> Regards
> Stéfan
> _______________________________________________
> Scipy-dev mailing list
> Scipy-dev@scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
> 


      


More information about the Scipy-dev mailing list