On 2009-09-21 10:09+0200 Werner Smekal wrote: > Hi, >> >> One thing I've been doing in my professional projects of late, is using >> doxygen. I find the standard doxygen style that depends on all the '*' >> characters to be really ugly, but since I mostly code in C++, there is the >> alternative of ///, which annoys me, but not as badly as " * ", plus those >> dorky header/trailer tokens. >> >> I've not tried doxygen on a C code base before, so I'm not sure if there >> are >> options that are more visibly appealilng than the standard/default. >> Without >> looking into it a bit first, I'm not in a postion to propose a specific >> style >> for function comment blocks. But I thought I throw out the doxygen option >> in >> case anyone else is interested in that, and able to summarize some of the >> options. > > Since I use myself doxygen a lot for my own code, I started to "doxyfy" the > PLplot source code. I added a Doxygen configuration file and changed on > source code file (plpage.c) so that Doxygen can filter the description for > the functions. I copied the output of doxygen to the net: > > http://www.miscdebris.net/plplot_doxygen/ > > You need to click "File List" on the left and then "plpage.c" to see some > source code documentation > I did that, since I regularly wander around the plplot core code not finding > what I need and I know that doxygen makes that a lot easier with cross > references and so on. Question is now, > > 1) if everybody agrees to "doxyfy" the plplot source code > 2) if everybody agrees how I documented the functions > > If it's ok, then I start the doxyfying process and everybody else is welcome > to join.
Hi Werner: I think this would be a superb and powerful replacement for our normal in-source documentation. I have a small amount of experience with doxygen via the libLASi project and was much impressed by it. Following your instructions above to refer to plpage (and the functions defined within that source code) confirmed just how useful this could be to us. I must emphasize this should be seen as excellent supplement to our already existing DocBook form of API documentation. doxygen is good at giving the quick details an experienced PLplot library developer needs plus all the important internal cross-references for our implementation. In contrast, our DocBook form of API documentation can be more general; it should be aimed more for external programmers who are using our API but who have no need to know about the internal details of our implementation of that API. So, yes please, go ahead as far as I am concerned with "doxygenating" our in-source documentation. However, I do have some further comments and suggestions. * We mostly do this already with our in-source documentation, but I wanted to mention the general principle of keeping the doxygen form of that documentation as short as possible for each of our functions (e.g., use one sentence rather than a paragraph to describe the function or one of its parameters). This documentation should be considered a short reminder aimed at experienced PLplot library developers and not something more comprehensive that you might expect from our DocBook form of API documentation. I think the current level of detail we have for plgspa (http://www.miscdebris.net/plplot_doxygen/plpage_8c.html#ac9d7c35262ab1c80cc1ed9bf15f7f128) is just about right. So this is not a criticism of what we have now. Instead, I just wanted to state the principle to be clear how this documentation potentially differs in brevity from the DocBook form of our API documentation. * For each of our functions please put in a cross-reference to the website form of documentation for that same function that is generated by DocBook in order to give everybody access to the broader overview that implies. * Currently those DocBook-generated URL's are in the versioned form http://plplot.sourceforge.net/docbook-manual/plplot-html-5.9.5/*.html. Regardless of how this doxygen project goes, I plan to change those URL's to the unversioned form, i.e., http://plplot.sourceforge.net/docbook-manual/plplot-html/*.html since it should help other websites as well as our doxygen-generated one to have a constant URL to refer to for our html documentation generated by DocBook. Anyhow, assume the unversioned form when doing the cross-references from the doxygenized code comments. * The URL's for the current form of our doxygen documentation are a mess (as can be seen from the form of plgspa URL above). Is there a configuration parameter to shorten those to something that is comprehensible (and thus guaranteed to be constant) such as .../plplot_doxygen/plpage.c_plgspa.html? I think we should cross-reference every doxygen function reference from our corresponding DocBook API documentation, but this is only practical with a non-changing form of URL for everything that doxygen documents. You may have that already, but a comprehensible URL without a bunch of random numbers in it is useful in many other ways as well. * Location. The generation of documentation in doxygen form should be part of our release tarball and also our SourceForge website. I would be happy to help out there by doing the appropriate changes to our build system and making an additional script to populate our website with the results. To move forward with this, please send me the doxygen commands you recommend to generate the html version of our doxygen results in our build tree. I can take it from there. Alan __________________________ Alan W. Irwin Astronomical research affiliation with Department of Physics and Astronomy, University of Victoria (astrowww.phys.uvic.ca). Programming affiliations with the FreeEOS equation-of-state implementation for stellar interiors (freeeos.sf.net); PLplot scientific plotting software package (plplot.org); the libLASi project (unifont.org/lasi); the Loads of Linux Links project (loll.sf.net); and the Linux Brochure Project (lbproject.sf.net). __________________________ Linux-powered Science __________________________ ------------------------------------------------------------------------------ Come build with us! The BlackBerry® Developer Conference in SF, CA is the only developer event you need to attend this year. Jumpstart your developing skills, take BlackBerry mobile applications to market and stay ahead of the curve. Join us from November 9-12, 2009. Register now! http://p.sf.net/sfu/devconf _______________________________________________ Plplot-devel mailing list Plplot-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/plplot-devel
