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

josef.pktd@gmai... josef.pktd@gmai...
Mon Jun 22 17:45:32 CDT 2009


On Mon, Jun 22, 2009 at 5:32 PM, Ralf
Gommers<ralf.gommers@googlemail.com> wrote:
>
>
> On Mon, Jun 22, 2009 at 4:41 PM, <josef.pktd@gmail.com> wrote:
>>
>> 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.
>
> scipy.interpolate is a module, so I assume you mean the classes in it. For
> some classes it is done correctly (see interp2d), other classes have both
> class and constructor documented (see interp1d). Doc writing has mainly
> concentrated on numpy so far, and there I have not come across classes with
> both class and constructor being documented.
> I agree it would be very useful for someone to go through scipy modules and
> move things around.

interp1d, KroghInterpolator and family, UnivariateSpline and family:
all the constructor information is in the __init__ docstring.

I'm going through scipy myself, but I haven't seen any clear pattern
for good class documentation yet. But if the consensus is to stick
with adding all information into the class docstring, I will start to
move them in interpolate, and clean up the others as I stumble upon
them.

just another random choice for class documentation: I just tried to
understand what numpy.poly1d is as a class, e.g. attributes and
methods.
It has good examples in the class docstring, but what are the methods,
what is p.r and p.c? (try to find it without looking at the source)


What if we want to document some private methods? What's the
corresponding header to "Other Parameters" for other methods?

And I would still like to see heavier use of autoclass at least in the
html and htmlhelp doc, with classes and methods on one page.

I hope your effort on the numpy docs will create some improvement to
the class documentation, so I can use the help file also for classes
instead of reading the source.

Just to emphasize it again, the htmlhelp for numpy and scipy is really
great, instantaneous access to most of the documentation. (I wish some
other packages, like matplotlib, would provide it also, instead of
(*args, *kwargs) popup signatures.)

Josef


>
>>
>> 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.
>
> agreed
>>
>>
>> How do we treat other class specific headers?
>> e.g "Internal Methods" in
>> http://docs.scipy.org/scipy/docs/scipy.stats.kde.gaussian_kde/
>
> Internal Methods is not a part of the documentation standard. Was this
> discussed on the list last year? I thought the consensus was that methods
> that are part of the API go under Methods, the rest is not listed in the
> class docstring.
>
> Ralf
>
>>
>>
>> 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
>>
>> >
>> >>
>> >> --
>
> _______________________________________________
> Scipy-dev mailing list
> Scipy-dev@scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
>
>


More information about the Scipy-dev mailing list