On 2011-01-10 09:48-0800 David MacMahon wrote:
> This is the first pass at adding some doxygen 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.
> Any feedback would be most appreciated!
Thanks for this.
I believe the level of explanation you have put in here for zops and
zp is just right from the developer perspective. I would simply copy
it wherever zops and zp are used elsewhere. Also, I think your
doxygen style (e.g., dropping the colons) is an improvement on what we
have done before so I will update the doxygen commentary in
pllegend.c, plpage.c, and plsym.c accordingly. I have committed your
patch (with some minor changes) as revision 11461.
Here is what I suggest for more detailed explanation of zops and zp in
the docbook documentation that is suitable for users. Create another
subsection of advanced.xml which describes how zops and zp are used in
low-level languages like C and also in higher-level languages like
Python. Then refer to that subsection whenever zops and zp are part
of the argument list of any function documented in api.xml.
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