On 2011-01-04 23:51-0800 David MacMahon wrote: > > This is the first pass at adding some commentary to the new(-ish) > functions that support arbitrary storage of 2-D data. Please let me > know if this is on the right track. I think most of the related > functions will have similarly worded explanations, so perhaps it would > be better to document the concept in one place and then refer to it from > each of the relevant functions. More commentary can be seen in the > commit log of r10864. >
Hi Dave: Could you use the doxygen style to document the function and its arguments? See pllegend in src/pllegend.c for a recent example (all the //! comments before pllegend and other functions in that file). I have little doxygen experience so don't follow what I did in pllegend.c too religiously if you have more doxygen experience than I do. If you have doxygen on your path, then the default now is to configure a doxygen documentation build. That's a dependency of the "all" target, but you can also generate it separately using the "build_doxygen" target which only takes a few seconds to complete. The result will be found in doc/doxygen/html/index.html in the build tree which you should browse with your browser. That index.html page is mostly blank, but if you follow the file link to pllegend.c, you can see how pllegend arguments are documented in detail by the doxygen-style comments in pllegend.c. Werner deserves credit for coming up with the idea "doxygenating" our source code. He paved the way by doing that for src/plpage.c. I think this is a great idea which should be propagated to every function in the src subdirectory. Much of that src documentation is done already so often it is a matter of simply transforming the code comments to doxygen-style comments. You should also check at doc/docbook/src/api.xml or the appropriate chapter in our on-line documentation at http://plplot.sourceforge.net/docbook-manual/plplot-html-5.9.7/ for argument documentation and overall documentation of each function which may be more up-to-date than the current code comments. I am still trying to figure out some hard and fast rules about the differences in style we would like to see between our doxygen and docbook documentation, but the fundamental thing to remember is doxygen documentation is largely for developers while docbook documentation is largely for users so probably the former documentation should be more terse than the latter. However, this distinction is already pretty fuzzy since much of the original docbook-style documentation of our API started life as code comments in the src subdirectory that were copied word for word to api.xml. Doxygen-style documentation is a good quick project to do if you are reviewing some component of our code in any case. I would be happy to receive doxygen patches (or api.xml patches, for that matter, if that turns out to be inconsistent with the code) from anybody that wanted to help us out by improving our documentation. 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 __________________________ ------------------------------------------------------------------------------ Learn how Oracle Real Application Clusters (RAC) One Node allows customers to consolidate database storage, standardize their database environment, and, should the need arise, upgrade to a full multi-node Oracle RAC database without downtime or disruption http://p.sf.net/sfu/oracle-sfdevnl _______________________________________________ Plplot-devel mailing list Plplot-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/plplot-devel
