On Mon, May 24, 2010 at 8:06 PM, David Cournapeau <[email protected]>wrote:
> On Tue, May 25, 2010 at 3:01 AM, Charles R Harris > <[email protected]> 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 > 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
_______________________________________________ NumPy-Discussion mailing list [email protected] http://mail.scipy.org/mailman/listinfo/numpy-discussion
