There are a large variety of hand-crafted files in our source tree which specify the public API for some component of PLplot, and it is very easy for these files to get out of synch. Therefore, I have just committed a script called scripts/check_api_completeness.sh that checks whether at least the list of names of PLplot functions is identical between the various API definition files for docbook, swig, octave, f77, and f95, and our fundamental definition of our public API in include/plplot.h.
I have made no attempt to make this script cross-platform so it is likely only to work on Linux. However, it is extremely useful there. ** Swig scripts/check_api_completeness.sh swig shows that our swig interface is consistent ** Docbook scripts/check_api_completeness.sh docbook \ |grep '[+-]' |grep -v '@@' |grep -v '\-\-\-' |grep -v '+++' yields the following results: -plarrows -plimage -plot3dcl -plsurf3dl which shows which functions have missing API documentation in doc/docbook/src/api.xml. (The missing documentation for plimage was discovered by Hez, yesterday, which was the original motivation for writing this check script.) I looked a bit further into the plarrows case, and we use something entirely different for our "arrows" example 22 and there is a comment in bindings/swig-support/plplotcapi.i that it is deprecated. However, it is not yet official deprecated by moving its source to pldeprecated.c and moving its documention to doc/docbook/src/api-obsolete.xml. Andrew (Ross), do you think it is time to officially deprecate plarrows, and if so, will you please do the honors? plot3dcl and plsurf3dl are on my ToDo list to document. ** Octave scripts/check_api_completeness.sh octave \ |grep '[+-]' |grep -v '@@' |grep -v '\-\-\-' |grep -v '+++' yields the following results: +plhls -plmap -plmeridians -plot3dcl +plrgb +plrgb1 -plscmap0a -plscmap1a -plscmap1la -plsetopt -plsmem -plsurf3dl The plhls, plrgb, and plrgb1 results show that those officially deprecated functions are implemented in our octave interface. Andrew (Ross), would you be willing to remove those or do you want to wait until the C removal of those currently deprecated functions? The "-" results shows there are quite a few PLplot functions in our public API that are missing from the octave interface. ** f77 (and f95) scripts/check_api_completeness.sh f77 \ |grep '[+-]' |grep -v '@@' |grep -v '\-\-\-' |grep -v '+++' yields the following results: -plarrows -plenv0 -plgcolbga -plgfci -plimage -plmap -plmeridians +plmapc +plmeridiansc -plot3dcl +plsetmapformc -plsfci -plsurf3dl and similarly for f95. The reason why plmap is missing and plmapc is found even though not present in plplot.h and similarly for plmeridians and plmeridiansc is a "c" suffix was used for these functions rather than the more usual "7". Arjen, is there any reason for that "c" suffix on plmap and plmeridians or may I change it to "7" (or f77) to be consistent with every other fortran function defined by our api? Arjen, I don't know what to make of +plsetmapformc. Could you comment? The remaining "-" results are because quite a few functions are missing from our f77 and f95 API's. ** Java While writing this I was reminded there is a hand-crafted java file (bindings/java/PLStream.java) that is supposed to give complete public API coverage so I implemented an additional check of that. Here are the results (as of revision 8265). scripts/check_api_completeness.sh java \ |grep '[+-]' |grep -v '@@' |grep -v '\-\-\-' |grep -v '+++' -plarrows -plgfci -plmap -plmeridians -plsfci -plshade1 -plsmem We have discussed plarrows above, and plshade1 and plsmem are mentioned but deliberately not implemented in bindings/swig-support/plplotcapi.i, but the rest are genuinely missing functions in the java API. If anybody here knows of any other hand-crafted file in our source tree that mentions the entire public API, please let me know (or, better yet, add the appropriate stanza to scripts/check_api_completeness.sh to check the file against the standard results derived from include/plplot.h). 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 __________________________ ------------------------------------------------------------------------- This SF.net email is sponsored by: Microsoft Defy all challenges. Microsoft(R) Visual Studio 2008. http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/ _______________________________________________ Plplot-devel mailing list Plplot-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/plplot-devel
