[SciPy-dev] Doc-ing classes and data attributes
Mon Jun 22 11:19:14 CDT 2009
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.
"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
More information about the Scipy-dev