################################################################################
# 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.