[Numpy-discussion] Extending documentation to c code

[David Goldsmith]

On Mon, May 24, 2010 at 11:01 AM, Charles R Harris <
charlesr.harris at gmail.com> wrote:

> Hi All,
>
> I'm wondering if we could extend the current documentation format to the c
> source code. The string blocks would be implemented something like
>
> /**NpyDoc
> """The Answer.
>
> Answer the Ultimate Question of Life, the Universe, and Everything.
>
> Parameters
> ----------
> We don't need no stinkin' parameters.
>
> Notes
> -----
> The run time of this routine may be excessive.
>
> """
> */
> int
> answer_ultimate_question(void)
> {
>     return 42;
> }
>
> and the source scanned to generate the usual documentation. Thoughts?
>
> Chuck
>

IMO it would be necessary to make such doc have the same status w.r.t. the
Wiki as the Python source; how much tweaking of pydocweb would that require
(Pauli is already over-committed in that regard; Joe, Perry, and I are
taking steps to try to alleviate this, but nothing is close to materializing
yet).  I know that as far as Joe and I are concerned, getting pydocweb to
support a dual review process is a much higher, longer-standing priority.

Also, quoting from the docstring standard: "An optional section for
examples...while optional, this section is very strongly encouraged."
(Personally, I think this section should be required, not optional, for
functions, and methods which require their own docstrings.)  But requiring
docwriters to supply working (i.e., compilable, linkable, runable) c code
examples (which would appear to be necessary because the coders appear to be
loath to provide their docstrings with examples) might be asking too much
(since we try to keep the doc writing effort open to persons at least
comfortable w/ Python, though not necessarily w/ c).

Unless and until these concerns can be realistically and successfully
addressed, I'm a strong "-1".

DG
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/numpy-discussion/attachments/20100524/97ec2d49/attachment.html>