[Numpy-discussion] Extending documentation to c code

[Charles R Harris]

On Mon, May 24, 2010 at 2:11 PM, David Goldsmith <d.l.goldsmith at gmail.com>wrote:

> 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".
>
>
I'm not interested in having this part of the standard user documentation
since the  c functions are mostly invisible to the user. What I want is
documentation for maintainers/developers of the c code. The c code is
essentially undocumented and that makes it difficult to work with,
especially for new people. At one time in the past I suggested using doxygen
but that didn't seem to arouse much interest. I've also tried generating a
call graph but only managed to crash the system... Anyway, it needs to be
done at some point and I'm looking for suggestions.

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