This document describes Version 1.10 of CPPDOC, a HTML-document generator for C++ classes.
//@p
) for
"private" documentation
CPPDOC reads C++ class header and implementation files and produces a HTML-document. CPPDOC is implemented in REXX.
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:
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).
CPPDOC and this document are Copyright (c) 1996 by BernhardBablok
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.
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.
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.
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 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.
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.
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 *.hppThis 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.
You can modify a CPPDOC created index file or write your own as long as the expected structure is retained:
<LI><A HREF="doc-file for className">className</A> [text]Note that LI must be capitalized.
</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.
The index file is only updated if necessary. New classes are added to the index just before the last </UL>-tag.
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:
#define className foo class className {...};will produce the document className.htm for class className.
class className { void foo(); /* function foo */ };foo() will not be recognized. Use // instead.
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.