[SciPy-dev] Doc-ing classes and data attributes
Mon Jun 22 11:27:43 CDT 2009
Boy, did I open a can of worms! :-(
--- On Mon, 6/22/09, Robert Kern <firstname.lastname@example.org> wrote:
> From: Robert Kern <email@example.com>
> Subject: Re: [SciPy-dev] Doc-ing classes and data attributes
> To: "SciPy Developers List" <firstname.lastname@example.org>
> Date: Monday, June 22, 2009, 9:19 AM
> 2009/6/22 Stéfan van der Walt <email@example.com>
> > 2009/6/22 Pauli Virtanen <firstname.lastname@example.org>:
> > >> 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
More information about the Scipy-dev