This file shows how to implement, configure, build, and test our
doxygen form of documentation.

* Implementation.  Doxygen documentation consists of comments in
  source code with a special leading prefix.  For our C source code
  the adopted doxygen prefix style we use is "//!".  See
  src/pllegend.c for an example of such comments which are largely up
  to date for that source file.  However, there are many other source
  files in src where the doxygen comments are only part done or not
  done at all.  It is our long-term goal to complete all of these
  making the doxygen wording describing the formal arguments
  consistent with our API description in doc/docbook/src/api.xml.
  Implementation of this goal could be partially automated by
  transforming the DocBook form of documentation in
  doc/docbook/src/api.xml into a temporary file in correct doxygen
  form.  This could be done in python using the
  http://docs.python.org/library/xml.etree.elementtree.html approach
  or we could follow the perl approach that is already implemented in
  docbook/bin for a number of other transformations of the api.xml
  documentation.  However we decide to do this automation, it would
  reduce the hand-editing work to copying the appropriate parts of the
  temporary file in doxygen form that is generated by the python or
  perl script to the appropriate parts of the files in src.

* Configuration.  This is all done using the configurable Doxyfile.in
  file.  This file needs to be adjusted from time to time to drop or
  add certain files to the list of files that are processed by
  doxygen.  Also, this file needs to be consistent with the doxygen
  version that is installed.  That should be done by running the

doxygen -u Doxyfile.in

  command (and committing the result) whenever the doxygen build (see
  below) emits a warning message concerning doxygen version
  consistency.

* Building the doxygen documentation.  This is done by configuring the
  CMake-based build of PLplot using the cmake command-line option
  -DBUILD_DOX_DOC=ON and running

make -j16 build_doxygen >& build_doxygen.out

* Testing the doxygen results.

  + Check build_doxygen.out for any error or warning messages.  Note,
    the code parsing functionality of doxygen is often at odds with
    the code-parsing functionality of gcc with regard to what warnings
    are issued.  For example, currently the generated
    bindings/qt_gui/plplotqt_autogen/*/moc_qt.cpp code is generating
    some (likely specious) warning messages from doxygen.

  + Browse the results.  For example, browsing the doxygen-generated
    page at doc/doxygen/html/pllegend_8c.html in the build tree should
    yield good-looking results, and similarly for all other files in
    the source tree that are documented via doxygen-related comments.