[SciPy-dev] Doc-ing classes and data attributes
Mon Jun 22 14:03:29 CDT 2009
2009/6/22 Stéfan van der Walt <email@example.com>
> 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
> 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
> What is the plan here? We must be able to execute the doctests in some
>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
> 409 Class instances normally take the docstring of the class. In
> the Numpy
> 410 namespace some class instances are made available to expose
> 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::
> 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.
> 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...
More information about the Scipy-dev