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?
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
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.
DG