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

[Robert Kern]

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