[SciPy-dev] Doc-ing classes and data attributes
Mon Jun 22 14:11:29 CDT 2009
On Mon, Jun 22, 2009 at 12:19 PM, Robert Kern <email@example.com> wrote:
> 2009/6/22 Stéfan van der Walt <firstname.lastname@example.org>
> > 2009/6/22 Pauli Virtanen <email@example.com>:
> > >> 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
> > >> necessary. On the other hand, it makes sense: you call "x =
> > >> 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
> > > constructor via eg. :ref:`ndarray <ndarray.__init__>` which might
> > > 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.
I prefer this as well. Why make it more complicated unless there's a good
Also, IPython will maybe still be able to do the right thing if both class
and __init__ are documented, but the standard Python prompt's help()
function will not. And there are still a lot of users of the standard
prompt, simply because it's the standard.
> 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
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the Scipy-dev