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".