[Numpy-discussion] Extending documentation to c code

[David Cournapeau]

On Tue, May 25, 2010 at 3: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?

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