On Mon, May 24, 2010 at 8:06 PM, David Cournapeau <cournape@gmail.com> wrote:
On Tue, May 25, 2010 at 3:01 AM, Charles R Harris
> 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).


This does sound promising/a good first step.  But it doesn't really answer Charles' question about a standard (which would be useful to have to help guide doc editor design).  My proposal is that we start w/ what we have - the standard for our Python code - and figure out what makes sense to keep, add, change, and throw out.  If we don't yet have an SEP process, perhaps this need could serve as a first test case; obviously, if we already do have an SEP, then we should follow that.