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

Charles R Harris charlesr.harris@gmail....
Mon Jun 22 15:59:13 CDT 2009


On Mon, Jun 22, 2009 at 10:19 AM, Robert Kern<robert.kern@gmail.com> wrote:
> 2009/6/22 Stéfan van der Walt <stefan@sun.ac.za>
>>
>> 2009/6/22 Pauli Virtanen <pav@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.
>

Same here.

Chuck


More information about the Scipy-dev mailing list