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

[David Goldsmith]

Boy, did I open a can of worms! :-(

DG

--- On Mon, 6/22/09, Robert Kern <robert.kern at gmail.com> wrote:

> From: Robert Kern <robert.kern at gmail.com>
> Subject: Re: [SciPy-dev] Doc-ing classes and data attributes
> To: "SciPy Developers List" <scipy-dev at scipy.org>
> Date: Monday, June 22, 2009, 9:19 AM
> 2009/6/22 Stéfan van der Walt <stefan at sun.ac.za>
> >
> > 2009/6/22 Pauli Virtanen <pav at iki.fi>:
> > >> We have to decide: is it OK to document the
> class constructor in
> > >> __init__?  We used to put this in the class
> docstring itself so that
> > >> "help" and IPython's "?" would find it, but I
> don't think this is longer
> > >> necessary.  On the other hand, it makes
> sense: you call "x = MyClass()"
> > >> to construct, not "x = MyClass.__init__()".
>  Comments welcome.
> > >
> > > IMHO, it would be clearer if the __init__ method
> was documented
> > > separately. It can be included on the same page
> in the Sphinx output as
> > > the class quite easily. This would allow separate
> referring to the class
> > > constructor via eg. :ref:`ndarray
> <ndarray.__init__>` which might result
> > > to cleaner documentation.
> >
> > I wouldn't mind changing this part of the standard.
>  Robert, I
> > remember you had a preference last time, do you want
> to comment?
> 
> I have always preferred documenting the __init__'s
> Parameters in the
> class docstring because one calls the class object itself.
> 
> --
> Robert Kern
> 
> "I have come to believe that the whole world is an enigma,
> a harmless
> enigma that is made terrible by our own mad attempt to
> interpret it as
> though it had an underlying truth."
>  -- Umberto Eco
> _______________________________________________
> Scipy-dev mailing list
> Scipy-dev at scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
>