[Plplot-cvs] SF.net SVN: plplot:[12538] trunk/doc/README.doxygen

[<ai...@us...>]

Revision: 12538
          http://sourceforge.net/p/plplot/code/12538
Author:   airwin
Date:     2013-09-27 15:53:14 +0000 (Fri, 27 Sep 2013)
Log Message:
-----------
Initial commit of documentation concerning how to implement,
configure, build, and test our doxygen form of documentation.

Added Paths:
-----------
    trunk/doc/README.doxygen

Added: trunk/doc/README.doxygen
===================================================================
--- trunk/doc/README.doxygen	                        (rev 0)
+++ trunk/doc/README.doxygen	2013-09-27 15:53:14 UTC (rev 12538)
@@ -0,0 +1,48 @@
+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=ON and running
+
+make 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
+  doc/doxygen/html/index.html that is generated by doxygen in the
+  build tree.  Then click on Files ==> pllegend.c result to see the
+  doxygen results for, e.g., pllegend.c.  And similarly for all other
+  files in src.

This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.