Documentation for doxygen documentation generator
=================================================

There are three ways you can use this tool:

1. As a replacement for your existing compiler
2. As a replacement for the 'doxygen' tool
3. As a 'lint' for doxygen comments

These three choices will be explained below.

1. The updating mechanism
----------------------

The documentation generator will write documentation entries for any newly
encountered function declarations, parameters for these functions and
variable declarations encountered, documenting them in the appropriate
place as explained below.  These will be clearly marked as 'TODO' in
both the source code and doxygen's generated output, in order to assist
in locating undocumented entries.

2. As a replacement for your existing compiler
-------------------------------------------

In this mode of operation, any pure documentation files contained within
the project will be updated.  Pure documentation files are source files
containing only documentation.

After updating these files, your compiler may be invoked in the usual way.

To use the tool in this way, there are many steps that must be carried out:

a. Every pure documentation file within your project must be included
(via the #include preprocessor directive) into every source file in
your project.  The easiest way to do this is to create a header file
with the relevant #include statements and ensure it is included into
every file, for example by including it into a common header file.
This file may be generated by the following command for new projects
(assuming GNU version of the find utility):

find /full/path/to/src -name '*.docs' -printf '#include <%p>\n' > docs.h

where:

  - /full/path/to/src is the full path to your source directory
  - *.docs is the pattern matching your pure documentation files
  - docs.h is the documentation header file

This command is included for convenience in the generateDocsHeaderFile
command.

b. Every documentation header file must end with a declaration of the form:

extern int SAGE_Doxygen_Dummy_xyz;

where xyz is an arbitrary string.  This is due to limitations within ROSE.
To perform this manipulation to your own pure documentation files, you
may use the following command at the root of your source tree (assuming
GNU find):

find . -name '*.docs' -exec sh -c 'echo extern int SAGE_Doxygen_Dummy_$RANDOM$RANDOM$RANDOM\; >> {}' \;

where:

  - *.docs is the pattern matching your pure documentation files

c. Replace all references to your usual compiler within your Makefile
or other build tool with a call to the correctExternalComments command.
This command takes the following parameters:

-doxygen:createNewFiles -- Required
-doxygen:classNameTemplate <template> -- template for the destination filename of any newly documented classes
-doxygen:functionNameTemplate <template> -- template for the destination filename of any newly documented functions
-doxygen:variableNameTemplate <template> -- template for the destination filename of any newly documented variables
-doxygen:updateScript <script> -- script that is run whenever a new documentation file is created

The template parameters may contain a placeholder %s which represents the
name of the class, function or variable.  The script parameter may contain
a placeholder %s representing the name of the file.  The updateScript
should update the documentation header file to include the newly created
documentation file.

It is recommended that absolute paths be used for filename templates if
your project uses multiple directories, as relative paths will not be
accurate as the build process descends into the project tree.

Below is a sample command line for a particular project:

correctExternalComments -doxygen:createNewFiles -doxygen:classNameTemplate /path/to/src/docs/%s.docs -doxygen:functionNameTemplate /path/to/src/docs/global.docs -doxygen:variableNameTemplate /path/to/src/docs/global.docs -doxygen:updateScript 'echo "#include \"%s\"" >> docs.h'

If you wish to compile your project in the same pass, you may change
correctExternalComments above to correctExternalCommentsAndCompile

3. As a replacement for the 'doxygen' tool
---------------------------------------

In this mode of operation, all files referenced by the 'Doxyfile' or
doxygen configuration file will be updated.  Each file will be compiled
separately, and for this reason it is important that every header
file referenced by the doxygen configuration file be self-contained,
i.e. it will include any of its dependencies.  The INCLUDE, FILE_PATTERNS,
EXCLUDE, INCLUDE_PATHS and DEFINES parameters of the doxygen configuration
file will be honored, should these be required.

The command to invoke this is called readDoxyfile, and should be run
in the directory containing the doxygen configuration file Doxyfile,
or with the path to the file as the only parameter.

The readDoxyfile is a Perl script and calls the ROSE translator
"correctAllComments", which can take header files and/or "*.docs"
files are source files.

As a 'lint' for doxygen comments
--------------------------------

The 'lint' tool will point out any mistakes in your documentation.
Currently it will only check if a function has multiple documentation
entries pertaining to it, causing one of these entries to be ignored (any
external entries will be ignored with the current version of doxygen).
To run the 'lint' tool, follow the procedure in Section 2a-b, but replace
any references to the compiler command in your makefile with 'docLint'.
