Hi Alan, >> >> 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.
That's exactly how I see the doxygen documentation too - as a supplement for the PLplot developer, not as a replacement for our existing DocBook documentation. > > 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. Agreed. > > * 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. Already added and will do from now on. > > * 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. Agreed as well, but I didn't find any option yet - need to ask the Doxygen mailing list. > > * 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. I don't know if it should be part of the relase tarball, since the documentation produced by doxygen is already 2.3Mb big - maybe because of the search function (index). So I'm not sure if it's fully documented, this just makes the release tarball much too big. The cmake build system should be no problem - in the moment you just need to run "doxygen" in the source tree - the documentation will be build in ./doc/code. Obviously the "Doxyfile" need to be copied to the build tree and "doxygen" run there. Searching the internet via google for "cmake doxygen" reveals some help about using doxygen with cmake (there is a package for it). > > 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 -- Dr. Werner Smekal Institut fuer Allgemeine Physik Technische Universitaet Wien Wiedner Hauptstr 8-10 A-1040 Wien Austria DVR-Nr: 0005886 email: sme...@iap.tuwien.ac.at web: http://www.iap.tuwien.ac.at/~smekal phone: +43-(0)1-58801-13463 (office) +43-(0)1-58801-13469 (laboratory) fax: +43-(0)1-58801-13499 ------------------------------------------------------------------------------ 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
