mirror of
https://github.com/boostorg/circular_buffer.git
synced 2026-01-22 05:02:14 +00:00
53 lines
2.5 KiB
Plaintext
53 lines
2.5 KiB
Plaintext
################################################################################
|
|
# 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.
|