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

[Ralf Gommers]

On Sat, Jun 20, 2009 at 11:12 PM, David Goldsmith
<d_l_goldsmith@yahoo.com>wrote:

>
> --- On Sat, 6/20/09, Ralf Gommers <ralf.gommers@googlemail.com> wrote:
>
> > On Sat, Jun 20, 2009 at 8:41 PM,
> > David Goldsmith <d_l_goldsmith@yahoo.com>
> > wrote:
> >
> > Thanks, Pierre, this is helpful, but the given example
> > doesn't have any of the _other_ sections Functions have,
> > though the docstring standard says "all but Returns are
> > relevant," so I'm left wondering where to insert
> > the "new" sections relative to the
> > "old."  (I know that not _all_ Function sections
> > will always be relevant for _all_ classes, but I assume at
> > least some of them will be relevant for some classes, but
> > your example doesn't clarify where to put them.)  But,
> > FWIW, thanks.
> >
> > 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 few I can think of
right away are
- documenting class instances
- documenting constants
- the [out] parameter

Ralf
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.scipy.org/pipermail/scipy-dev/attachments/20090621/1731209b/attachment.html