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

josef.pktd@gmai... josef.pktd@gmai...
Mon Jun 22 15:41:38 CDT 2009


On Mon, Jun 22, 2009 at 3:11 PM, Ralf
Gommers<ralf.gommers@googlemail.com> wrote:
>
>
> On Mon, Jun 22, 2009 at 12:19 PM, 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.
>
> 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.


pythons help is actually very informative but our documentation is
not. Whatever the decision, we should adjust the current docstrings so
that they actually get included in the generated docs.
E.g. scipy.interpolate: after last years discussion a large part of
the information is only available as docstring to the __init__ method.
If we stick with documenting the constructor in the class docstring,
then we should move them.

As an enhancement to the doc editor, it would be nice if it would also
show the generated documentation from an autoclass directive. This
would reduce the guessing about whether and how the docstrings will
show up.

How do we treat other class specific headers?
e.g "Internal Methods" in
http://docs.scipy.org/scipy/docs/scipy.stats.kde.gaussian_kde/

I hope some nice examples come out of this, so we can include some of
the left out class documentation in scipy without a lot of guessing.

Josef

>
>>
>> --
>> 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@scipy.org
>> http://mail.scipy.org/mailman/listinfo/scipy-dev
>
>
> _______________________________________________
> Scipy-dev mailing list
> Scipy-dev@scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
>
>


More information about the Scipy-dev mailing list