[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: is the C++ interface documented/stable?

Hi,

Dan Kelley <address@hidden> asks:

> > Documentation Improvements
> > ...
> > ...
> > The supplementary class documentation for the C++ interface has also been
> > revised and expanded.
> 
> I don't see this in the web page at
>   http://www.unidata.ucar.edu/packages/netcdf/guide_toc.html
> I see summaries of the "C" and "FORTRAN" interfaces, but only a
> couple of lines about how C++ differs from C.

Yes, the revised and expanded documentation for the C++ interface is in the
cxx/ subdirectory of the new netCDF 2.4 source release.  It's not integrated
with the C and Fortran documentation in the NetCDF User's Guide, because we
decided that reorganizing the User's Guide to usefully document three or
more language bindings was difficult, and it might be better to instead have
a language-independent part and language-dependent supplements specifying
the bindings and providing examples for each language.

> Is there a separate website for the C++ documentation?  Or am I
> missing something in my very brief perusal of the docs?

There is now a separate web document for the supplementary C++
documentation.  Thanks for pointing out the need for this.  It's at

    http://www.unidata.ucar.edu/packages/netcdf/cxxdoc_toc.html

and is also accessible from the top-level netCDF web page at

    http://www.unidata.ucar.edu/packages/netcdf/

> I ask because the C++ interface is important to me, and we've had a
> lot of problems getting it working.  This was a year or so back, and
> the unidata folks were quite helpful in guiding us to hacks to fix
> things, but they claimed that the C++ interface was still
> experimental.  What is the status now?  Is the C++ interface
> purposefully not documented, so that unidata can make changes later if
> they like?  

The C++ interface is still less mature than the C and Fortran interfaces,
but thanks to users like you and contributions from other developers
(especially Dan Schmitt), it's been improving.  We no longer consider it
experimental, and intend to try to support the currently-documented
interfaces.  The state of the documentation is definitely not a consequence
of a desire to reserve the right to make incompatible changes in the future.

To further improve the C++ interface, we need at least:

 - a more exhaustive test of the interface than the current superficial test
   of a few of the member functions;

 - addition of exception handling;

 - better integration with the C++ standard libraries, e.g. use of standard
   C++ strings, STL iterators, ...; and

 - more experience using the C++ interface in real programs.

I hope to be working on these for a future release of netCDF.

______________________________________________________________________________

Russ Rew                                           UCAR Unidata Program
address@hidden                              http://www.unidata.ucar.edu