[Numpy-discussion] Extending documentation to c code

[David Goldsmith]

On Mon, May 24, 2010 at 4:59 PM, Charles R Harris <charlesr.harris at gmail.com
> wrote:

>
>
> 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
>
> Not checking in un-/poorly documented new code would be a good start.

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