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

[Ralf Gommers]

On Mon, Jun 22, 2009 at 12:19 PM, Robert Kern <robert.kern at gmail.com> wrote:

> 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.
>

I prefer this as well. Why make it more complicated unless there's a good
reason?
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
> Scipy-dev at scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20090622/77d57d54/attachment.html>