|
From: <ai...@us...> - 2013-09-27 15:53:16
|
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.
|