On Tue, May 25, 2010 at 3: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?
I have thought about this for quite some time, but it is not easy. Docstrings are useful because of cross references, etc... and documentation for compiled code should contain signature extraction. For those reasons, I think a doc tool would need to parse C, which makes the problem that much harder. Last time I looked, synopsis was interesting, but it does not seem to have caught up. Synopsis was interesting because it was modular, scriptable in python, and supported rest as a markup language within C code. OTOH, I hope that clang will change the game here - it gives a modular, robust C (and soon C++) parser, and having a documentation tool written from that is just a question of time I think. Maybe as a first step, something that could extract function signature would be enough, and writing this should not take too much time (Sebastien B wrote something which could be a start, to autogenerate cython code from header:http://bitbucket.org/binet/cylon). David