| ################################################################################ |
| # HOW-TO documentation about generating/updating source code documentation for # |
| # the Circular Buffer library. # |
| # # |
| # Copyright (c) 2003-2008 Jan Gaspar # |
| # # |
| # Use, modification, and distribution is subject to the Boost Software # |
| # License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at # |
| # http://www.boost.org/LICENSE_1_0.txt) # |
| ################################################################################ |
| |
| The source code documentation (i.e. documentation of functions, classes and |
| their methods, etc.) is part of the source code. This makes it convenient for |
| a developer when browsing source files or developing new (documented) code. |
| The source code documentation is included in the larger, more detailed library |
| documentation as well which makes it more convenient for the user of the |
| library. In order to make it easier for the developer, the source code |
| documentation included in the library documentation is generated from the source |
| files. Which means the developer does not have to write the same source |
| documentation twice. |
| |
| Prerequisites: |
| |
| 1) Unix/Linux shell (with sed editor) available. |
| (The script can be easily converted into Windows batch file if you do not |
| have access to Unix/Linux shell.) |
| 2) Installed Doxygen http://www.doxygen.org. |
| (Source documentation generation was tested with the Doxygen version |
| 1.4.6.) |
| 3) Installed xsltproc http://xmlsoft.org/XSLT/xsltproc2.html. |
| 4) Installed HTML Tidy http://tidy.sourceforge.net. (Tested with version |
| released on 1 September 2005.) |
| |
| |
| Updating source code documentation: |
| |
| The source code documentation of the Circular Buffer library obeys the Doxygen |
| syntax. The library documentation is written in HTML (files circular_buffer.html |
| and space_optimized.html). The generation of the source code documentation is |
| performed by executing the update_srcdoc.sh script which relies mainly on |
| Doxygen and several XSL transformations. |
| |
| After editing the source code documentation in the source file(s), update the |
| library documentation by executing: |
| |
| $>./update_srcdoc.sh circular_buffer |
| |
| for the circular_buffer or/and |
| |
| $>./update_srcdoc.sh circular_buffer_space_optimized |
| |
| for the circular_buffer_space_optimized. |