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

[Stéfan van der Walt]

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.

 	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.

 	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.

Regards
Stéfan

2009/6/22 Ralf Gommers <ralf.gommers@googlemail.com>:
>
>
> 2009/6/21 Stéfan van der Walt <stefan@sun.ac.za>
>>
>> 2009/6/21 Ralf Gommers <ralf.gommers@googlemail.com>:
>> > The CodingStyleGuidelines page is generated from
>> > /trunk/doc/HOWTO_DOCUMENT.txt so editing on Trac is not what you want.
>> > The
>> > page is already in reST format, so can we add it to the doc editor and
>> > edit
>> > it there?
>>
>> The documentation standard should not be open to editing.  You are, of
>> course, welcome to provide patches that we can apply after discussion,
>> but this document cannot be in a state of flux.
>
> You're right that it should not be in a state of flux. I attached a patch to
> #1146 for review.