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

[David Goldsmith]

--- On Sat, 6/20/09, Ralf Gommers <ralf.gommers at googlemail.com> wrote:
<big snip>
> > Look at ndarray for an example: http://docs.scipy.org/numpy/docs/numpy.ndarray/#numpy-ndarray
> 
> > Documenting the class indeed means its __init__
> 
> > function as far as Parameters, See Also, Examples,
> etc. This
> 
> > is what has been done so far for all classes I've
> looked
> 
> > at.
> 
> > The Methods and Attributes sections show up
> automatically,
> 
> > and contain all public methods/attributes, so
> don't
> 
> > worry about putting a list of those in. Those
> 
> > methods/attributes do have their own docstrings.
> 
> If I may have edit privileges at http://projects.scipy.org/numpy/wiki/
> I can add these clarifications there myself; otherwise,
> I'll file a ticket at pydocweb.
> 
> The CodingStyleGuidelines page is generated from
> /trunk/doc/HOWTO_DOCUMENT.txt so editing on Trac is not what
> you want. The page is already in reST format, so can we add
> it to the doc editor and edit it there?  
> 
> I'd like to be able to make changes to it as well, a

Glad to see I'm not the only one. ;-)

> few I can think of right away are 
> - documenting class instances
> - documenting constants
> - the [out] parameter

Regarding this last, as per a suggestion from Pauli in the Discussion following ndarray.rst, I just now finished adding a "See also, numpy.doc.ufuncs, 'Output arguments' section" to the ndarray methods possessing the [out] parameter (actually, I added it to the docstrings of their equivalent functions outside of the ndarray namespace), so keep this in mind when contemplating what to add in the HOWTO_DOCUMENT.txt. :-)

DG

> Ralf
> 
> 
> 
> 
> -----Inline Attachment Follows-----
> 
> _______________________________________________
> Scipy-dev mailing list
> Scipy-dev at scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
>