CPPDOC - A Documentation Generator for C++ Classes

This document describes Version 1.11 of CPPDOC, a HTML-document generator for C++ classes.

What's New

1.11

CPPDOC now also can read files containing tabs.

1.10

Various features were added to influence the behaviour of CPPDOC, mainly

options controlling the amount of output
option to select relative links
option to process input files twice
an additional documentation tag (//@p) for "private" documentation
ability to process more than one filespec
filespecs with wildcards are also allowed

To process all options, the interface of CPPDOC has changed significantly.

1.00

The intial release.

Overview

CPPDOC reads C++ class header and implementation files and produces a HTML-document. CPPDOC is implemented in REXX.

Installation

Just copy the file cppdoc.cmd to a directory in your PATH.

The commandline syntax has changed considerably from version 1.0 to 1.1. CPPDOC now uses the GetOpt-port from Lawrence R Buchanan to process commandline arguments. His package (getopt.zip) is available from various ftp-sites.

CPPDOC is now invoked from a commandline using the syntax:

cppdoc [-x indexFile] [-t targetDirectory] [-rH2sdim] file [file ...]

The indexFile is optional and is used to create links to other class documentation, see Index Files for details.

The targetDirectory specifies the directory where class documentation will be placed (CPPDOC will generate one HTML-file for each class declaration found). Default is the current directory.

Using the -r option will generate relative links in index and class documentation files (execpt for links to source files). Default are absolute links.

The -H option will hide all lines with the documentation-tag "//@p". This option is useful if you want to generate different documentation for different users (e.g. more complete doc for maintainers of the source code). For details, see Private Documentation.

Using the -2 option will process all files twice. This is necessary to generate correct links to all classes in all files. The option can be omitted if the index file already contains an entry for every class.

The -sdim options specify which parts of the documentation should be generated:

-s will generate a link to the source files
-d will generate the class description
-i will include the class inheritance and interface
-m will include the member description

The default is to generate everything. If you use any one of the above options, all other parts will only be included if specifically requested.

After all options you can give one or more filespecs. The wildcards "*" and "?" will be expanded before processing begins.

All files should contain one or more class declarations. CPPDOC will look in the same directory as the file for an implementation file with the extension cpp, cc, cxx or c (in that order).

License Agreement

CPPDOC is distributed in the hope that it is useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

You are allowed to use and modify CPPDOC, but your are not allowed to sell CPPDOC or redistribute modified versions of CPPDOC publicly.

Comments of any kind are welcome, especially if you think you discovered a bug. In this case, please check the section Restrictions first.

Modifying CPPDOC

If you want to create a version of CPPDOC suitable for your national language, you have to change the constants in the initConstants internal subroutine of CPPDOC. All headings are defined as constants, as well as two constants for translating special national characters to their HTML-equivalents. These constants are named NLS_CHAR and NLS_CHAR_ESC. The current values are for German texts (my native language). There must be exactly one space between individual characters and between escape sequences. A list of those escape sequences can be found in the document http://www.sandia.gov/sci_compute/symbols.html.

If you provide me with the values of NLS_CHAR and NLS_CHAR_ESC for your national language, I will include them in the next version.

Basic Functions

CPPDOC creates a source section, an inheritance section and a class interface section for every class declaration found in the header file.

For additional documentation, you have to add documentation tags to your source files. These tags define class and function documentation and are automatically extracted. CPPDOC will produce an internal link from the class interface section to every function documented with a documentation tag.

In the source section, links are included to the source files. Up to now, the WebExplorer does not recognize *.hpp and *.cpp files as "Plain Text", although they usually have this file type. These links are therefore for future (improved) versions of WebExplorer.

Documentation Tags

Class Documentation

Class documentation is identified by a section of code preceeding the class declaration in the form:

    //@ index entry for class foo
    //@ First line of class documentation
    //@ .
    //@ .
    //@ .
    //@ Last line of class documentation

    class foo {
       void fkt(int i);
    };

The first line is always considered to be a short text for the index file, the following lines are extraced and included in the class documentation section of the created document. You can include HTML-tags into this section, but you shouldn't use any heading-tags.

Function Documentation

Function documentation is similarly identified by a section of code preceeding the function definition in the form:

    //@ First line of function documentation
    //@ .
    //@ .
    //@ .
    //@ Last line of function documentation

    void foo::fkt(int i) {...
    };

Again, the documentation is extraced and included in the function documentation section of the created document. In addition, an internal link is created from the function declaration in the class interface section to the appropriate function documentation.

Free functions (e.g. friends) are documented in the document of the class of the last preceeding member function.

Private Documentation

The tag //@p defines "private" (not in the C++ sense) documentation. If the -H option is supplied to CPPDOC, all lines with this tag are removed. Otherwise, the p in the tag is replaced by a blank.

Index Files

Rational

Using CPPDOC without an index file produces only internal links from the class declaration to functions defined in the header or implementation file. To link to documentation of other classes, you have to provide CPPDOC with an appropriate index file.

If you supply an index file name on the commandline, and the file does not exist, then CPPDOC will generate the file. Subsequent calls to CPPDOC with the same index file will update the file if necessary.

To create all links for all class declarations in a directory you have to run CPPDOC with the option -2:

cppdoc -x index -2 *.hpp

This creates the file index.htm in addition to all class documentation files. In the first pass, index entries are created for all classes declared in all header files. The second pass will create all external links within the individual documents.

Structure

You can modify a CPPDOC created index file or write your own as long as the expected structure is retained:

Every line starting with a <LI>-tag (leading spaces are ignored) is considered as an index entry and must have the form
```
<LI><A HREF="doc-file for className">className</A> [text]
```
Note that LI must be capitalized.
There must be at least one line starting with
```
</UL>
```
This line is necessary for adding new entries to the index. Again the UL should be capitalized.

If you want to group the index entries, you can have CPPDOC generate an index file for you, and edit it to include e.g. heading levels. If you need unordered lists in your modified index file, just make shure you spell the <li>-tag and the </ul>-tag with lowercase letters.

Update

The index file is only updated if necessary. New classes are added to the index just before the last </UL>-tag.

Restrictions

CPPDOC uses a rather primitive language parser, and this is the reason why not every syntactically correct code is supported (incorrect code might also lead to errors). In detail, you have to observe the following rules:

HPFS is required unless your class names have at most eight characters.
Constructions like
```
     #define className foo
     class className {...};
```
will produce the document className.htm for class className.
CPPDOC won't identify function names in class declarations correctly if the function returns some complex type involving parenthesis (like pointer to function). Use a typedef instead (I recommend this even if you don't use CPPDOC).
Don't use class names identical to HTML-tags and constructs (like A, HREF, NAME etc). This will confuse CPPDOC when trying to create external links.
Declarations and definitions of operator-functions must have the keyword operator and the opening parenthesis on the same line.
Declarations of conversion operators (operator T()) are identified as member functions T(), but are linked correctly. This is more an aesthetic issue, the operator-part is not highlighted in the link color.
CPPDOC won't identify the class declaration correctly if you have unbalanced braces in comments within the declaration.
CPPDOC assumes that a line containing the chars /* and */ is a plain comment. Therefore in the construct
```
     class className {
        void foo();       /* function foo */
     };
```
foo() will not be recognized. Use // instead.
CPPDOC expects function definitions to appear after all class declarations.

The order of declaration (and use) of functions and the order of implementation must be the same. This is especially important for overloaded functions. In

     class foo {
        foo() {}
        foo(int k);
        ~foo() {
           // ...
           cleanup();
        }
        void cleanup();
     };
     ...
     //@ constructor taking one argument.
     foo::foo(int k) {...}
     ...
     //@ Cleanup of resources
     void foo::cleanup() {...}

the first constructor is linked to the definition of the second constructor and the call to cleanup() in ~foo() is linked to the definition of cleanup(). It is safest not to define any functions within the class declaration and to use inline definitions instead:

     class foo {
        foo();
        foo(int k);
        ~foo();
        void cleanup();
     };

     //@ Default constructor
     inline foo::foo() {}

     //@ constructor for foo taking one argument.
     foo::foo(int k) {...}

     //@ Destructor
     inline foo::~foo() {
           // ...
           cleanup();
        }

     ...
     //@ Cleanup of resources
     void foo::cleanup() {...}

If you plan to use the //@p-tag to hide overloaded functions, you should declare them after all non-hidden functions with the same name.

Place function definitions of non-class functions after a definition of a member function. This ensures that the function is documented in the correct document. In a strict sense a non-class function is not part of the class and shouldn't be documented together with a specific class, but in reality these functions are friends or closely related (like overloaded operators).