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

[Ralf Gommers]

2009/6/22 Stéfan van der Walt <stefan@sun.ac.za>

> Hi Ralf
>
> Thanks for the patch!  I committed your fixes up to the point where
> you start discussing class documentation.
>
> 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.
>
> A couple of questions and comments about the patch:
>
>        326        Not all examples will run though, due to them including
> blank lines
>        327        in the output. Do not put in doctest-specific markup like
>        328        ``<BLANKLINE>`` or ``#doctest: +SKIP``, readability is
> more important
>        329        here than being able to execute the doctests in a testing
> framework.
>
> What is the plan here?  We must be able to execute the doctests in some
> way.
>

>From previous emails on the list (from Robert) I learned that we do not
execute these doctests, and do not even have a way of doing that at the
moment. If that's not correct then the ``#doctest: +SKIP`` should stay. If
it is correct, then doctest directives are just noise that the user should
not see.


>        409     Class instances normally take the docstring of the class. In
> the Numpy
>        410     namespace some class instances are made available to expose
> certain
>        411     functionality.
>
> I know what you mean by the above, but I think these sentences are a
> bit confusing.
>

I'll rephrase and give a concrete example.


>
>        419     Documenting constants
>
> To which constants are you referring?  Give an example to clarify.
>
>        436     * [,out] : All ufuncs accept an optional `out` argument.
> This is
>        437       documented in the **Output arguments** section of
> `doc.ufuncs`. In the
>        438       docstring this argument should be documented like this::
>        439
>        440         out : ndarray, optional
>        441             Array into which the output is placed. Its type is
> preserved and
>        442             it must be of the right shape to hold the output.
> See
> `doc.ufuncs`.
>
> I think we can leave this out of the standard, since it pertains to a
> very specific part of numpy.


Maybe it doesn't belong in the standard, but it should be somewhere so we
get these things done as uniformly as possible. I'd be happy with a wiki
page for points like this.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.scipy.org/pipermail/scipy-dev/attachments/20090622/b6623346/attachment.html