[Numpy-discussion] Tests and code documentation

[David M. Cooke]

On Thu, 21 Sep 2006 10:05:58 -0600
"Charles R Harris" <charlesr.harris at gmail.com> wrote:

> Travis,
> 
> A few questions.
> 
> 1) I can't find any systematic code testing units, although there seem to be
> tests for regressions and such. Is there a place we should be putting such
> tests?
> 
> 2) Any plans for code documentation? I documented some of my stuff with
> doxygen markups and wonder if we should include a Doxyfile as part of the
> package.

We don't have much of a defined standard for docs. Personally, I wouldn't use
doxygen: what I've seen for Python versions are hacks, whose output looks
like C++, and which requires markup that's not like commonly-used conventions
in Python (\brief, for instance).

Foremost for Python doc strings, I think, is that it look ok when using pydoc
or similar (ipython's ?, for instance). That means a minimal amount of
markup.

Someone previously mentioned including cross-references; I think that's a
good idea. A 'See also' line, for instance. Examples are good too, especially
if there's been disputes on the interpretation of the command :-)

For the C code, documentation is autogenerated from the /** ... API */
comments that determine which functions are part of the C API. This are put
into files multiarray_api.txt and ufunc_api.txt (in the include/ directory).
The files are in reST format, so the comments should/could be. At some point
I've got to through and add more :-)

-- 
|>|\/|<
/--------------------------------------------------------------------------\
|David M. Cooke                      http://arbutus.physics.mcmaster.ca/dmc/
|cookedm at physics.mcmaster.ca