On Sun, Mar 09, 2008 at 04:48:27PM -0700, Alan Irwin wrote: > 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.
Alan - great idea. Thanks for this. > 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? I replace plarrows with the more flexible plvect / plsvect about 4 years ago. plarrows has not appeared in the examples since then. I'm happy to officially depreciate it. SVN commit in progress. I have moved plarrows to pldepreciated.c and removed from the common API. It now prints a warning that the function is depreciated and you should use plvect instead. I removed it from the ada bindings (not implemented properly anyway - but we don't want it to propagate in a new binding). Swig already had it commented out. Only exists in C++ and octave. For backwards compatibility I won't remove at this stage. > 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. My thoughts are conservative - let's leave it in until we fully remove the functions. I will add warnings, as for plarrows. This way we give users and developers some notice before the function disappear. Removing functions is a major API change and not something I would do lightly. > ** 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. I'll look at these and get back to you. I'm sure there was a logic at one stage. plarrows (deprecated - now removed from CAPI). plmap / plmeridians - a transform function is passed as an argument which is not supported in many languages. plgfci / plsfci - this is an oversight, mostly because it is not used in an examples. Volunteers to devise an example? plshade1 - again issues with passing functions. plsmem - issues with memory handling in a cross language context. Andrew > 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 > ------------------------------------------------------------------------- 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
