On Mon, May 24, 2010 at 2:11 PM, David Goldsmith <d.l.goldsmith@gmail.com> wrote:
On Mon, May 24, 2010 at 11:01 AM, Charles R Harris <charlesr.harris@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

"""The Answer.

Answer the Ultimate Question of Life, the Universe, and Everything.
We don't need no stinkin' parameters.

The run time of this routine may be excessive.

    return 42;

and the source scanned to generate the usual documentation. Thoughts?


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.