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 -j4 build_doxygen >& build_doxygen.out

* Testing the doxygen results.  Do this by checking build_doxygen.out
  for any error or warning messages.  Then use a browser to look at
  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.
