On Mon, May 24, 2010 at 4:59 PM, Charles R Harris wrote: On Mon, May 24, 2010 at 2:11 PM, David Goldsmith 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 /**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