CPPDOC - A Documentation Generator for C++ Classes

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

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.

Usage

CPPDOC is invoked from a commandline using the syntax:

cppdoc headerFile [indexFile]

The headerFile should contain one or more class declarations. CPPDOC will look in the same directory as headerFile for an implementation file with the extension cpp, cc, cxx or c (in that order). The indexFile is optional and is used to create links to other class documentation, see Index Files for details.

CPPDOC will generate one HTML-file for each class declaration found.

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

There should be a space between the //@ and the text that follows. At the moment, this is not strictly necessary, but in future versions, I want to use the character after the //@ to identify something like "private documentation".

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.

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 the following command twice:

for %1 in (*.hpp) do cppdoc %1 index

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, that is, if the class name currently processed is not already part of the index. 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.
CPPDOC doesn't like tab-characters. If your editor produces tabs, use a conversion filter before using CPPDOC.
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() {...}

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

CPPDOC - A Documentation Generator for C++ Classes

Table of Contents: