1. Introduction
2. Using Ccdoc
   1. Use Case 1: Document a simple C++ header file.
   2. Use Case 2: Document a simple C++ header file with custom colors.
   3. Use Case 3: Document a simple C++ header file with a link to a custom page and custom header and trailer info.
   4. Use Case 4: Document a simple C++ header file with a different name for @root.
   5. Use Case 5: Document the root package.
   6. Use Case 6: Where is ccdoc.index.html?
   7. Use Case 7: Document multiple C++ header files in a single directory.
   8. Use Case 8: Document multiple C++ header files in multiple directories.
   9. Use Case 9: Document namespaces.
   10. Use Case 10: Document a class.
   11. Use Case 11: Capture the on-line help in a log file.
   12. Use Case 12: Tell ccdoc to ignore sections of code.
   13. Use Case 13: Tell ccdoc to link to the related source cosde.
   14. Use Case 14: Run ccdoc from an MS-DOS command prompt.
   15. Use Case 15: How do I expand wildcards in MS-DOS?
   16. Use Case 16: How do I determine which version/release of ccdoc I have?
   17. Use Case 17: How do I add custom hyperlinks to the @see directive?
   18. Use Case 18: What does the -rpthpc switch do?
   19. Use Case 19: How can I change the indent level on the class summary page?
   20. Use Case 20: How can I change variable width font in the code section to a fixed width font?
   21. Use Case 21: How can I fix mangled links to my HTML directory under DOS?
   22. Use Case 22: How can I specify a C++ style, single line, suffix comment in ccdoc?
   23. Use Case 23: How do I specify a link to an operator in the{@link ..} and @see directives?
3. Comment Syntax
   1. Format
   2. Directives
      1. /**, */
      2. /**<,*/, /*!<,*/
      3. /**@#-*/, /**@#+*/
      4. /**@#=<ch>*/
      5. //@{, //@}
      6. //@-, ///<, //!<
      7. @@
      8. @author
      9. @deprecated
      10. @exception
      11. @link, @endlink
      12. @param
      13. @pkg
      14. @pkgdoc
      15. @pkgdoctid
      16. @returns
      17. @see
      18. @since
      19. @suffix
      20. @throws
      21. @todo
      22. @version
      23. {@link...}
4. Program Phases
   1. Phase Independent Switches
   2. Phase 1: Parsing
   3. Phase 2: Indexing
   4. Phase 3: HTML generation
5. Database Details
   1. Verbose Format
   2. Terse Format
6. Release Notes

Ccdoc is a free javadoc inspired tool that automatically generates HTML web documentation from C++ programs by parsing the source file headers. It was designed to aid collaboration between package users and package developers by documenting the interface. Although I tried very hard to stay true to the javadoc syntax and tool flow, I was forced to change (or add) a few things because of language differences like pre-processing directives, templates and namespaces.

Here are the design goals of ccdoc and some of the design decisions that were influenced by the goals.

• It should be easy to use.
  • There is no setup
  • You cannot specify include paths, although you may have to specify macro definitions.
  • It is easy to run. A simple command line invocation is all that is needed to document an entire system (in many cases).
• Controllable
  • You can control which sections of code that ccdoc processes.
  • You can generate your own output format by parsing the database format.
  • You can modify the source code to add or remove your features.
• Robust
  • A number of regression tests have been added to verify the operation of this program.
  • Uses STL extensively

For more information about ccdoc, see the official ccdoc website: http://ccdoc.sourceforge.net.

This section describes how to use ccdoc in different environments. It is organized as a series of successively more complex examples.

Use Case 1: Document a simple C++ header file.

This example shows how to generate documentation for a single package with a single source file.

% mkdir webdocs
% ccdoc -db simple.db simple.h -html webdocs/

Here is what simple.h looks like:

// ================================================
//@{
// This is the brief description of the simple function.
//
// The simple function takes in two integer arguments,
// adds them together and then returns the result.
// @param x The x value.
// @param y The y value.
// @returns The sum of x and y.
//@}
// ================================================
extern "C" unsigned simple(unsigned x,unsigned y);

Here are the files that are generated:

• ccdoc.class_summary.html
• ccdoc.root.pkg
• ccdoc.root.simple.-22C-22.unsigned.simple.-28.unsigned.x.-2c.unsigned.y.-29.fct.html

Here is what the ccdoc documentation looks like for ccdoc.class_summary.html. This is the documentation for all of the classes in the system. Since there aren't any in this example, it is empty.

Here is what the ccdoc documentation looks like for ccdoc.root.pkg. This is the documentation for the root level package. In this case, the user did not specify any documention and didn't change the name.

Here is what the documentation looks like for the function.

There are three sections: the header, the body and the trailer.

The header has a single link called "@root" on the left side. This is the top level ccdoc package. The name can be changed using the -root switch and you can add your own link with the -rooturl switch. In addition, you can add customized HTML with the -header switch.

The header has a single link called "classes" on the right side. This is the link to the class summary.

The body describes the contents of the page. In this case it is a single, standalone function called simple.

The trailer describes the date/time the page was created, the version of ccdoc, etc. You can specify your own custom HTML here with -trailer switch.

Use Case 2: Document a simple C++ header file with custom colors.

This example shows how to generate documentation for a single package with a single source file in different colors.

% ccdoc -db simple.db simple.h -html webdocs/ \
	-bg black -fgtext yellow -fglink blue -fgvlink red

Here is what the ccdoc documentation looks like.

Use Case 3: Document a simple C++ header file with a link to a custom page and custom header and trailer info.

This example shows how to generate documentation for a single package with a single source file with a custom header, trailer and a rooturl.

% ccdoc -db simple.db simple.h -html webdocs/ \
	-header header.txt -trailer trailer.txt \
    -rooturl http://www.mystuff.com/htdocs/

Here is what the custom header looks like:

<center>
<h3>Header for example 3</h3>
</center>

Here is what the custom trailer looks like:

<center>
<font size=2>Trailer for example 3</font>
</center>

Here is what the ccdoc documentation looks like.

As you can see, the custom headers and trailers have been added. In addition, there is now a Home link in the upper left hand corner. This link points to http://www.mystuff.com/htdocs/. This capability allows you to link ccdoc generated documents to other documents in your system.

Use Case 4: Document a simple C++ header file with a different name for @root.

In the previous examples, the root level package was always called @root. This may not be desirable for many systems. This example shows how to change it.

% ccdoc -db simple.db simple.h -html webdocs/ \
	-root example4

Here is what the ccdoc documentation looks like:

As you can see, the "@root" in the upper left hand corner has been replaced by example4.

Use Case 5: Document the root package.

In the previous examples, the root level package was not shown but it was there.

In examples 1-3 the root level package file ccdoc.root.pkg.html. In example 4 the root level package was ccdoc.example4.pkg.html. In general, the root package name is ccdoc.<root>.pkg.html.

To document a root level package you create a ccdoc comment with the @pkgdoc directive using an @root target as shown in the example below:

% cat root.txt
// ================================================
//@{
// This is the root documentation for example 5.
//
// All of the files in this example do neat stuff.
// @author Joe Linoff
// @version 1.0
// @pkgdoc @root
//@}
// ================================================

The @root target specifies that this comment is associated with the root package, not with anything else.

Here is how you run the command:

% ccdoc -db simple.db simple.h root.txt -html webdocs/ \
	-root example5

Here is what the ccdoc documentation looks like for the root page:

Use Case 6: Where is ccdoc.index.html?

In previous versions of ccdoc, the root package was always named ccdoc.index.html. In this version this convention was changed because the root package was the same as any other package and I wanted the output to be consistent. Unfortunately, this means that many users might be stranded because they have already built systems that expect to find ccdoc.index.html.

This example shows how to create a root package file with the name ccdoc.index.html.

% ccdoc -db simple.db simple.h -html webdocs/ \
	-rootfile ccdoc.index.html

There is no interesting ccdoc documentation in this example.

Use Case 7: Document multiple C++ header files in a single directory.

This example shows how to document multiple C++ headers files in a single directory.

% ccdoc -db example7.db -html webdocs/ i/*.h

Use Case 8: Document multiple C++ header files in multiple directories.

This example shows how to document multiple C++ header files in multiple directories. It shows how to use packages to differentiate them. Packages are very powerful concept because they allow you to group the documentation for related files.

Unlike the earlier examples, this one requires multiple invocations of ccdoc in three general phases: parsing, indexing and HTML generation.

The first phase parses the sources file and assigns the statement entities to the specified packages as shown below.

% # PHASE 1
% ccdoc -db example8.db -pkg Utils Utils/i/*.h
% ccdoc -db example8.db -pkg Core Core/i/*.h
% ccdoc -db example8.db -pkg Algorithms Algorithms/i/*.h
% ccdoc -db example8.db root.txt

The second phase does internal processing to associate related statements.

% # PHASE 2
% ccdoc -db example8.db -index

The third phase generates the HTML files.

% # PHASE 3
% ccdoc -db example8.db -html webdocs/ -root example8

Use Case 9: Document namespaces

This example shows how to document namespaces.

Namespaces are documented just like any other C++ entity but, since a single namespace declaration can appear in multiple files, ccdoc uses a comment on any one of them. This is shown in the contrived example below:

% cat example9.h
// ================================================
//@{
// This namespace declares the group of classes
// that perform utility functions for this system.
//@}
// ================================================
namespace Utilities {
  void Read();
  void Write();
}

namespace Utilities {
  void Status();
}

Ccdoc will group all of the entities in the namespace together before reporting them.

The ccdoc documentation for the namespace is shown below:

Use Case 10: Document a class.

This example shows how to document a class. Here is the sample code:

// ================================================
//@{
// This class manages a point in 2D space.

//
// A point consists of two coordinates: x and y.
// The code fragment below shows how to use this class.

// <pre>
//@@ #include "point.h"
//@@ #include <iostream>
//@@  
//@@ using namespace std;
//@@  
//@@ int main() {
//@@    Point p1;
//@@    Point p2;
//@@    p1.x = 1;
//@@    p1.y = 1;
//@@    p2.x = 2;
//@@    p2.y = 2;
//@@    Point p3 = p1;
//@@    p3 += p2;
//@@    return 0;
//@@ }
// </pre>
// @author The Project Team
// @version 1.0
// @see Database::Record
//@}
// ================================================
class Point {
public:
  //@{
  // Default constructor.
  // Initializes x and y to zero.
  //@}
  Point() : x(0), y(0) {}
public:
  //@{
  // Copy constructor.
  // @param p The point to copy.
  //@}
  Point(const Point& p) : x(p.x), y(p.y) {}
public:
  //@{
  // Assignment operator.
  // @param p The point to assign.
  // @returns The updated point.
  //@}
  Point& operator = (const Point& p) {x=p.x;y=p.y;return *this;}
public:
  //@{
  // Addition operator.
  // @param p The point to add from.
  // @returns The updated point.
  //@}
  Point& operator += (const Point& p) {x+=p.x;y+=p.y;return *this;}
public:
  //@{
  //  The x coordinate. Note that this attribute is public
  //  because any value is valid and no state has to be
  // preserved.
  //@}
  int x;
  //@{
  //  The y coordinate. Note that this attribute is public
  //  because any value is valid and no state has to be
  // preserved.
  //@}
  int y;
};

The methods and attributes in this class show up on the HTML page because they are part of the class as shown below:

Use Case 11: Capture the on-line help in a log file.

There is a lot of interactive help available from ccdoc. In fact there is to much to capture conveniently on a screen. This use case shows how to capture the on-line help in a log file so that you can view it with your favorite text editor.

% ccdoc -log help.txt -help

Use Case 12: Tell ccdoc to ignore sections of code.

Ccdoc defines a pragma called "__ccdoc__" that can be used to insert or ignore sections of code when ccdoc is running. The example below shows how to use this pragma to ignore include guards:

#ifndef include_guard
#if !defined(__ccdoc__)

#define include_guard
#endif


.
.
.


#endif

This tells ccdoc to ignore the include_macro definition.

Use Case 13: Tell ccdoc to link to the related source code.

By default ccdoc puts a passive reference to the source code in the comment. If you would like to actually link to the real code you need to provide ccdoc with a URL that it can link to. You use the -srcurl switch for this.

Consider the case of file mytest.h that lives in a directory called /group/work/src which can be accessed from the web by the URL http://internal/group/work/src. To specify to ccdoc that you want to be able to access the file use the following command line:

% cd /group/work
% mdir webdocs
% ccdoc -db mytest.db src/mytest.h \
	-html webdocs/ \
	-srcurl http://internal/group/work

Here is what the source file looks like:

% cat src/mytest.h
extern int mytest_function();

When ccdoc runs, it will recognize prefix references to the "src/mytest.h" with "http://internal/group/work" and create a link in the source statement which will look like this:

Use Case 14: Run ccdoc from an MS-DOS command prompt.

Running ccdoc from an MS-DOS command prompt is a bit tricky because cmd.exe uses forward slash '/' to denote switches and a backward slash as a directory separator. The -dospath switch is provided to allow you to specify that you are running in the cmd.exe interpreter.

This switch was added because lots of folks use other shells, like rsh and tcsh under windows so ccdoc can't differentiate by the platform.

The MS-DOS command prompt is also challenging because it does not expand wildcards. This means that you must explicitly list each file.

Here is a sample run to create some ccdoc documentation under MS-DOS:

C:> dir /b i\*.h > hfiles.txt
C:> ccdoc -db db\test.db -files hfiles.txt
C:> ccdoc -db db\test.db -index
C:> ccdoc -db db\test.db -dospaths -html webdocs\

Use Case 15: How do I expand wildcards in MS-DOS?

This use case tells you how to expand wildcards in MS-DOS.

Wildcards are expanded automatically by ccdoc since r10 as shown below:

C:> ccdoc -db test.db -files *.h

If you have an earlier version, you can use the -files switch to specify a file that contains a list of files.

The way it works is that you must create a file that contains the list of files that you want to process and then you specify the -files <list> switch. The following example shows how this works:

C:> dir /b i\*.h > hfiles
C:> ccdoc -db test.db -files hfiles

Later on when you create the HTML, you must specify the dospaths switch so that ccdoc knows that it has to convert the backslashes to forward slashes for HTML references.

The follow example shows how this works:

C:> ccdoc -db test.db -dospaths -html webdocs\

Use Case 16: How do I determine which version/release of ccdoc I have?

This use case describes how to determine which release of ccdoc you have. In all versions of ccdoc released on or after August 27, 2001 you can use the -version switch as follows:

% ccdoc -version
ccdoc v0.8 r5 2001/08/27 bin_opt_msvc_MSWin32-4.0
^     ^    ^  ^          ^   ^   ^    ^
|     |    |  |          |   |   |    +---- os/version
|     |    |  |          |   |   +--------- compiler id
|     |    |  |          |   +------------- build type (opt or dbg)
|     |    |  |          +----------------- keyword
|     |    |  +---------------------------- build date
|     |    +------------------------------- revision
|     +------------------------------------ major version
+------------------------------------------ program id

If this doesn't work you have an older version. You should look at the first two lines of the help output to determine the release date of the help. You should also download the latest release.

Use Case 17: How do I add custom hyperlinks to the @see directive?

This use case shows how you can add your own hyperlinks to the @see directive. Ccdoc will not translate @see input that begins with a '<' character and it will output exactly as it was input. You can use this capability to create your own custom links as shown in the example below:

% cat example17.h
/**
 * This example shows how you can add custom hyperlinks
 * to the @see directive.
 * @see <a href=mydoc.html>Other Stuff</a>
 */
int example17;

Use Case 18: What does the -rpthpc switch do?

The rpthpc defines a different output format for package information. It represents the hierarchical information using indenting rather than scoped names.

Use Case 19: How can I change the indent level on the class summary page?

Use the -rptcsi switch.

Use Case 20: How can I change variable width font in the code section to a fixed width font?

Use the -rptfwcf switch.

Use Case 21: How can I fix mangled links to my HTML directory under DOS?

In most cases, mangled links occur because you specified one or more backslashes in the -html path as follows:

C\:> ccdoc -db foo.db -html mystuff\ *.h

This causes problems for the HTTP resolver because backslash is not a valid path separator. Change the backslashes to forward slashes to fix the problem.

C\:> ccdoc -db foo.db -html mystuff/ *.h

Use Case 22: How can I specify a C++ style, single line, suffix comment in ccdoc?

It is sometimes to useful to only add a short comment to items. Ccdoc provides a C++ style, single line, suffx comment form to do this. The syntax is '//@-'. An example usage is shown below:

class Point3D {
public:
  int p1; //@- The x coordinate.
  int p2; //@- The y coordinate.
  int p3; //@- The z coordinate.
};

This section describes the syntax of ccdoc comments.

Format

Ccdoc comments are organized into three parts: the short description, the long description and the directives.

The short description provides a relatively brief summary that shows up in the table of contents.

The long description provides a more detail description of the entity. It only shows up at the point where the entity is documented. Long descriptions are separated from short descriptions by a ccdoc directive or by period followed by a space, tab or newline. Actually there are two forms of short descriptions in ccdoc. The previous sentence described the default behavior. Here are the down and dirty details of the differences.

There are two forms of short descriptions allowed in ccdoc. The default form conforms to the javadoc specification in which the short description is terminated by a tag (directive) or by period that is followed by a space, tab or newline. As shown in the following example.

/**
 * The default (-jdsds) short description terminates
 * with a directive or period followed by space, tab
 * or new line. This is the start of the long description.
 *
 * This is more of the long description.
 */

The bold entries are the long description. The non-bold entries are the short description.

The other form is the old ccdoc style syntax that allows you specify short description until the end of the paragraph (a blank line). To use the old for specify the -nojdsds switch in phase1 processing. The example below shows the old form.

/**
 * The -nojdsds short description terminates
 * with a blank line. This is the NOT the start of the long
 * description.
 *
 * This is the start of the long description.
 */

The bold entries are the long description. The non-bold entries are the short description.

If you compare the two examples, you will see that the behavior is substantially different.

Note the default behavior of ccdoc with respect to short descriptions changed in r24. Prior to r24 -nojdsds was the default. After r24, -jdsds was the default.

Directives describe certain attributes of the comment. The @@, @link and @$ directives can be embedded anywhere. All of the other directives should appear at the end of the comment. Their order is not significant.

Ccdoc comments are attached to the next C++ entity unless the @pkgdoc or @suffix directives are specified. If @pkgdoc is specified, the comment is attached to a package. If the @suffix directive is specified, the comment is attached to the previous entity.

The example below shows a ccdoc comment with annotations designating the sections.

// ================================================
//@{                             <---- start of ccdoc scomment
// Short description.            <---- short description
// Long description paragraph 1. <---- long description
//                               <---- long description
// Long description paragraph 2. <---- long description 
// @author The Project Team      <---- directive
// @version 1.0                  <---- directive
// @see Database::Record         <---- directive
//@}                             <---- end of ccdoc comment
// ================================================

The example below shows a new form of abbreviated comment that allows you to specify single line, suffix style comments:

class Point5 {
public:
  int p1; //@- The v coordinate.
  int p2; ///< The w coordinate.
  int p3; //!< The x coordinate.
  int p4; /**< The y coordinate. */
  int p5; /*!< The z coordinate. */
};

Of course the old javadoc style comments are still supported:

/**                              <---- start of ccdoc scomment
 * Short description.            <---- short description
 *                               <---- separator
 * Long description paragraph 1. <---- long description
 *                               <---- long description
 * Long description paragraph 2. <---- long description 
 * @author The Project Team      <---- directive
 * @version 1.0                  <---- directive
 * @see Database::Record         <---- directive
 */                              <---- end of ccdoc comment

The next section describes each of the directives in detail.

Directives

Before describing each directive in detail, a quick reference table is provided.

Directive	Description
/** .. */	Encloses a javadoc style ccdoc comment.
/**<, /*!< .. */	Encloses a doxygen style suffix ccdoc comment.
/**@#-*/, /**@#+*/	Turn ccdoc token parsing off and on. It is used to turn off sections code.
/**@#=<ch>*/	Insert <ch> into the input stream. This is useful for inserting characters that only ccdoc can see.
//@{, //@}	Encloses a C++ style ccdoc comment.
//@-	Defines a single line, suffix, C++ style comment.
@@	Translate HTML special characters <,> and & into &lt;, &gt; and &amp; for code fragments.
@author	Specify an author. This directive can be specified multiple times to denote multiple authors. The first entry should be the original author.
@deprecated	Specifies that this entity has been deprecated and describes the alternatives to use.
@exception	Deprecated, same as @throws.
@link,@endlink	Generate a hyperlink to a ccdoc entity.
@param	Document a parameter to a function or class method.
@pkg	Specifies the name of a package in a file. The -pkg switch is preferred.
@pkgdoc	The comment that contains this directive documents a specific package not the following C++ entity.
@pkgdoctid	Redefine the output title id for a pkgdoc.
@returns, @return	Documents the return value from a function.
@see	Add a hyperlink entry to the See section.
@since	This entity has only been available since the specified version.
@suffix	This is a suffix comment which means this comment is associated with the previous C++ entity.
@throws	Document an exception. Same as @exception.
@todo	Specifies that there are additional things things to be done to this interface or its implementation.
@version	The version.
{@link .. }	Generate a hyperlink to a ccdoc entity.

 

Directive: /** .. */

These directives designate the beginning and ending of java style ccdoc comment that is associated with the next statement (a prefix comment). It is convenient and familiar but has the drawback of all multi-line comment styles in that runaway comments are hard to detect.

A simple example is shown below:

/**
 * This is the brief description that shows up in the table
 * that shows up in the table of contents.
 * This is where the longer description starts.
 * @author A. Programmer
 * @version 1.0
 */
void function(int a);

The leading asterisk on the lines in between is optional but recommended for readability.

This section describes the three phases of ccdoc.

Phase Independent Switches

This section presents the switches that can be used in any phase or,
as is the case with -h, no phase.

Switch	Description
-args	Dump the command line arguments. This is enabled automatically in verbose (-v) mode.
-cid	Deprecated. Same as -version.
-ctf <file>	Deprecated. Same as -db.
-db <file>	The name of the ccdoc database. The -ctf switch has been deprecated and may go away in future versions.
-h, -help	Displays the on-line help and exits.
-log <file>	All information output by the program is also sent to the specified log file. Multiple log files can be specified. By default all output is sent to cout. For an example of how this switch is used see use case 11.
-nocout	Turn off output to cout. This is used to test the help output without displaying anything to the console.
-putenv <env>	Set an environment variable from the command line. This is useful for setting up regression tests in scripts on various platforms
-[no]v	Turn verbose mode on or off. The default is off.
-version	Report the program version. The version contains the program name, the version, the revision, the release date and the compilation id. Here is an example of what the -version reports: % ccdoc -version ccdoc v0.8 r5 2001/08/27 bin_opt_msvc_MSWin32-4.0
-[no]vf	Turn db verbose format mode on or off. The default is verbose because it speeds up the writing significantly and the only slightly larger. This switch enables verbose mode in the database file to make things easier to read for debugging. For more information on the database formats click here.
-[no]warn	Turn warnings on or off. The default is on

Phase 1: Parsing

During the parse phase C++ files are parsed to find declarations and ccdoc comments. These entities are tokenized and stored into the database specified by the -db switch. The parse phase is specified by the -pkg switch or the presence of source files on the command line.

When new files are parsed, the indexing information from previous runs is lost.

Switch	Description
-[no]cdsm	Turn on or off the creation of default special members for classes. Specifically this tells ccdoc to create (or not create) entries for default constructors, copy constructors, destructors and copy operators if they were not explicitly defined in the class. The default is -cdsm.
-db <file>	The name of the ccdoc database. The -ctf switch has been deprecated and may go away in future versions.
-D<name>[=<value>]	Define a macro and, optionally, define its value. The __ccdoc__ macro is pre-defined by ccdoc.
-doxygen	New since r37. Enable limited doxygen compatibility mode. The default -doxygen. This switch specifies that: the @endlink directive is ignored the @file comment blocks are ignored the following single line comment forms are supported. int a1; //!< Variable a1. int a2; ///< Variable a2. int a3; /*!< Variable a3. */ int a4; /**< Variable a4. */ This allows users more flexibility in converting between doxygen and ccdoc.
-files <list>	New. Specifies a file that contains a list of files to process. This is convenient for MS-DOS where the command interpreter does no expand wild cards.
-[no]jdsds	New since r24. Enable javadoc short description syntax. This causes ccdoc to conform to the javadoc specification for processing short descriptions. This is the new default behavior as of r24. A javadoc short description is terminated by a period followed by a space, tab, newline or a tag (directive). If -nojdsds is specified, the old-style ccdoc short description handling is enabled. That is, short descriptions are terminated by a blank line.
-pkg <name>	Define the package name for the entities in the the source files. If no package is specified a default name is used or the @pkg <name> directive in the ccdoc comment is used. Children (like class methods) inherit the package from their parent. Names in the package hierarchy are separated by '::' or '.'. Thus, -pkg A::B::C denotes three packages, A is the parent of B and B is the parent of C.
-[no]tcms	New in r33. Turn on or off the processing of template class methods that are defined outside of the class declaration. The example below shows what is ignored: template <class T> struct Test { T Get() const {return m_val;} void Set(T v); T m_val; }; // This will be ignored by ccdoc // which implies that the ccdoc // comment must appear in the // declaration above. template <class T> Test<T>::Set(T v) {m_val=v;} The default is -notcms.
-U<name>	Undefine a macro.

Phase2: Indexing

During the index phase ccdoc analyzes the database to find associations between related entities. For example, if class Child derives from class Parent, this phase will find Parent and link it to the Child record so that a link can be generated during the output phase. The index phase is specified by the -index switch.

If the index phase is not run, the output will contain no links.

Switch	Description
-db <file>	The name of the ccdoc database. The -ctf switch has been deprecated and may go away in future versions.
-index	Generate index information.

Phase 3: HTML Generation

During the output phase, ccdoc generates HTML from the database. This phase is optional. A user could develop their db reader and output any another format (like XML). The output phase is specified by the -htm or the -html switch.

After this phase is run, a top level file called ccdoc.index.html will exist in the specified html path.

Switch	Description
-bg <color>	The background color. The default is the default for the browser.
-db <file>	The name of the ccdoc database. The -ctf switch has been deprecated and may go away in future versions.
-dospaths	New. The file paths contain backslashes that need to be converted to forwards slashes for HTML references.
-fg <color>	Same as -fgtext.
-fgtext <color>	The foreground text color. The default is the default for the browser.
-fglink <color>	The foreground link color. The default is the default for the browser.
-fgvlink <color>	The foreground vlink color. The default is the default for the browser. These are used links.
-header <file>	The HTML used for the customized header just after the <body> stmt. This is where clients insert their own custom information on each page.. See the -meta command for information on how to insert meta variables in the <head> section.
-html <prefix>	The HTML path prefix. This is used to designate the path where the HTML files will be stored. The directory suffix must be included if this is a directory path. Always use a forward slash to separate directories, even when you are running under a DOS window, because the HTTP path hierarchy separator is a forward slash.
-imageurl <URL> -img <URL>	Deprecated. The URL that describes of the GIF images. This version of ccdoc does not use images so this switch has no effect.
-[no]macros	Deprecated. Same as -[no]rptmac.
-maxpathlen <num>	Maximum file path size. The default is 128. When the file path size exceeds the limit, the file name is truncated and a checksum is added to guarantee that the file name is unique. If maxpathlen is set to zero, no limit checking is performed.
-meta <file>	The HTML used for the customized header just after the <head> stmt. This is where clients can insert their own custom information for meta variables on each page. If -meta is specified, ccdoc will not generate the the http-equiv meta variable for HTML 4.01 compliance and it will ignore the -rptctcs.
-[no]private	Deprecated. Same as -[no]rptpri.
-[no]protected	Deprecated. Same as -[no]rptpro.
-[no]public	Deprecated. Same as -[no]rptpub.
-root <name>	Change the name of the root package from 'root' to something else.
-rootfile <name>	Change the top level output file name from <prefix>ccdoc.root.pkg.html to whatever the user wants. This can be used to create the ccdoc.index.html file by specifying: -rootfile ccdoc.index.html. This switch allows you to completely specify the path. The -html prefix is ignored which means that you must be make sure that the output file is in the same directory as the other files generated by ccdoc so that the relative links work.
-rootpurl <URL> -rooturl <URL>	The hyperlink for the parent of the root package. Setting this allows the generated HTML to seamlessly integrate to a higher level document by providing a back link to the users parent page.
-[no]rptcfuns	Report comments for undocumented namespaces. When -rptcfuns is specified, all related namespaces comments are reported. This includes namespaces that do not contain ccdoc comments which can be somewhat busy. When -norptcfuns is specified, only related namespaces with ccdoc comments are reported. The only exception is when none of the namespaces have ccdoc comments. In that case, only the first undocumented namespace is reported (for backward compatibility). The default is -norptcfuns.
-[no]rptcsd	New. Report class summary details. When -rptcsd is specified, the class summary page reports type, access and short description information. When -norptcsd is specified the class summary page only reports the names. The default is -rptcsd.
-[no]rptcsi <num>	New in r15. The class summary indent switch. Define the indent level of each entry in the class summary report and the contents column. The default indent level is 4.
-rptctcs <string>	New in r22. Allow the user to specify the Content-Type char set. This allows international languages to be supported. The default char set is "iso-8859-1". This switch is ignored if the -meta switch is specified. If both -rptctcs and -meta are specified a warning is issued.
-rptdefa <string>	New in r20. Set the default string for the author field in top level entities. The default is "unascribed".
-rptdefasd <string>	New in r20. Set the default string for the automatically generated short description field in top level entities. The default is "automatically generated".
-rptdefsd <string>	New in r20. Set the default string for the automatically generated short description field in top level entities. The default is "undocumented".
-rptdefv <string>	New in r20. Set the default string for the version field in top level entities. The default is "unknown".
-[no]rptdpa	New. If the package author is not specified, report the author as unascribed. The default is -norptdpa which tells ccdoc to ignore authors on packages unless they are explicitly specified.
-[no]rptdpd	New. If the package description is not specified, report the description as unknown. The default is -norptdpd which tells ccdoc to ignore descriptions on packages unless they are explicitly specified.
-[no]rptdpv	New. If the package version is not specified, report the version as unknown. The default is -norptdpv which tells ccdoc to ignore version on packages unless they are explicitly specified.
-[no]rptfwcf	New in r15. The fixed width code font switch. Use a fixed width font when reporting code fragments. The default is -norptfwcf.
-[no]rpthpc	New. Report package contents hierarchically like the the class summary page. The default is -rpthpc.
-[no]rptim	New. Report all inherited methods as though they were defined locally. This allows you to read all of the methods that are available on a given class. The default is -rptim.
-[no]rptmac	New. Report macros. Default is -norptmac because there can be large numbers of guards in header files. If a system is designed with ccdoc in mind, the header guards can be surrounded by ccdoc guards (#ifndef __ccdoc__) which would make this data more useful.
-[no]rptmac1	New in r34. Report macros heuristically. This means that ccdoc attempts to filter out header guards and windows DLLIMPORT/DLLEXPORT macros by filtering out macro names with the following characteristics: Prefixes dll_,DLL_ include_,INCLUDE_ included_,INCLUDED_ Suffixes _dll,_DLL _h,_H _hh,_HH, _include,_INCLUDE _included,_INCLUDED _included_,_INCLUDED The default is -norptmac1. When this switch is enabled, it also enables -rptmac.
-rptmlci <num>	New in r37. Maximum length of the content ids. This switch is used to avoid strange looking tables of content when the id is very long. When the string exceeds this length, only the first <num> characters are printed followed by .. to indicate truncation. The default length is 32. A value of zero means don't impose the limit. If no inherited from column exists, the value of the -rptmlcifi is added to make this field bigger.
-rptmlcifi <num>	New in r37. Maximum length of the contents "inherited from" column id. This switch is used to avoid strange looking tables of content when the parent id is very long. When the string exceeds this length, only the first <num> characters are printed followed by .. to indicate truncation. The default length is 32. A value of zero means don't impose the limit.
-[no]rptpri	New. Report private items. The default is -norptpri.
-[no]rptpro	New. Report protected items. The default is -norptpro.
-[no]rptpub	New. Report public items. The default is -rptpub.
-[no]rptsci	New in r22. Report the class information in sorted order. The default is -rptsci. If -norptsci is specified the class contents and details are not sorted.
-[no]rptsrc	New in r37. Report the source information for each entity in the table of contents. This causes an additional column to be added to the table. The default is -norptsrc because this information is already reported for each entity in its description. It exists to provide debugging support for when no description is generated.
-[no]rpttyp	New. Report typedefs. Default is -rpttyp.
-[no]rptun	New. Report unions. Default is -rptun.
-sourceurl <URL> -srcurl <URL>	The URL where the source files can be found. If this is specified, hyperlinks are created for Source entries.
-trailer <file>	The HTML used for the customized trailer.
-[no]typedefs	Deprecated. Same as -[no]rpttyp.
-[no]unions	Deprecated. Same as -[no]rptun.

The database has changed in this version to accomodate namespace handling and better id parsing.

There are two database formats: verbose (-vf) and terse (-novf). The default is verbose because it is fastest.

Verbose Format

The verbose format does not attempt to re-use strings. The format of the file is:

<header>
<strings_header>
<strings>
<statements_header>
<statements>
<end_of_file>

Header

The header is always the first line. This is the contents of the verbose header:

 ccdoc v0.8 verbose

Strings Header

The string table follows the header. It is denoted by a '$' followed by the number of strings in the string table. It is always empty in verbose format because strings are not-reused. The syntax is:

<strings_header> ::= '$' <num> ;

The fragment below shows the string table entry:

$ 0

Strings

There are no string entries in verbose format.

Statements Header

Following that is the statements record. This reports the number of statements in the database (not access_specifiers and files). It is denoted by a 'S' followed by a number. All numbers in the database are stored in hex format. The syntax is:

<statements_header> ::= 'S' <num>

A database with 1 record would have an entry that looks like this:

S 1

Statements

There are three types of statement records: access_specifiers, files and statements.

Access specifiers start with an 'a' followed by a keyword: 'pri', 'pro' or 'pub' to indicate whether the following statements are private, protected or public. The syntax is:

<access_specifier> ::= 'f' 'pri' | 'f' 'pro' | 'f' 'pub' ;

All entities outside of a class are public. The fragment belows shows a sample access specifier statement:

a pub

File specifiers start with an 'f' followed by a hex number that specifies the number of characters in the string, followed by the string. The syntax is:

<file_specifier> ::= 'f' <strlen> <string> ;s

It indicates that the following statements are associated with this file. The fragment below shows a sample file statement:

f 5 foo.h

Statements are much more complex. They have the following syntax:

<statement> ::= 's' <id> <tag> <ptag> <type> <extern> <lineno> <tokens> ;
<id> ::= <strlen> <string> ;
<tag> ::= <num> ;
<pstag> ::= <num> ;
<type> ::= <statement::base terse name> ;
<extern> ::= <strlen> <string> ;
<lineno> ::= <num> ;
<tokens> ::= <num_tokens> <token_list> ;
<num_tokens> ::= <num> ;
<token_list> ::= <token> | <token_list> <token> ;
<token> ::= <strlen> <string> ;

The id is the name of the statement. The tag is the index id of the statement. It is used to verify database integrity. The ptag is the parent tag. This is used to re-create the statement tree. The type is a 3 character designator that specifies the statement type. These types can be found in statement.cc under terse names. The extern entry specifies the extern type. The lineno is the line number in the source file where there entity was found.

The tokens are the specific tokens associated with this statement. They have different meanings for different statement types.

For all statements except comments, they are the C++ tokens.

For ccdoc comments, the tokens have a specific syntax. The ccdoc token syntax is as follows:

@{
@file
    2
    <source_file>
    <lineno>
@type
    @prefix or @suffix
@short_desc
    <num_tokens>
    <tokens>
@long_desc
    <num_tokens>
    <tokens>
@params
    <num>
    @param
        <num>
        <name>
        <tokens>
@returns
    <num_tokens>
    <tokens>
@exceptions
    <num>
    @exception
        <num>
        <name>
        <tokens>
@deprecated
    <num_tokens>
    <tokens>
@authors
    <num_tokens>
    <tokens>
@version
     <token>
@sees
    <num>
    @see
        <num>
        <name>
        <tokens>
@since
    <num_lines (0 or 1)>
    <line>
@source
    <num_files (0 or 1)>
    <file>
@pkg
    <num_tokens>
    <tokens>
@pkgdoc
    <num_tokens>
    <tokens>
@}

The @{ and @} designate the begining and ending of the comment tokens. The @file specifies the source file and lineno. The type is either @prefix or @suffix. @prefix indicates that this comment is associated with the next statement. @suffix indicates that this comment is associated with the previous statement.

@short is the short description and @long is the long description.

You might find @link sprinkled throughout the token lists. This indicates that a link was specified using the @link or @$ directive. The syntax of the @link sub-statement is:

@link
<num_tokens>
<tokens>

The first token is the link, all of the other tokens are part of the anchor id.

@params is the list of parameters and @returns is the returns comments.

@exceptions is the list of exceptions, @deprecated is the deprecated comment and @authors is the list of authors.

@version is the version, @sees is the see also entries, @pkg is package and @pkgdoc specifies that this comment is for a specific package.

End of File

The end of the file is denoted by an 'e'.

Terse Format

The terse format is identical to the verbose format with the following exceptions: the string table has entries and <strlen> <string> pairs in the verbose format are replaced with tags.

Each string entry has the following syntax:

<tag> <strlen> <string>

Where <tag> is the index into the string table, <strlen> is the number of characters in the string and <string> is the string.

Terse mode uses less file space than verbose mode but the write operation is much slower.

For the latest information, see the news and issues sections of the ccdoc web page: http//ccdoc.sourceforge.net.

See the online help for the latest information about switches and directives.

This is the first new release since 1998. The program has been completely rewritten from scratch to conform to the latest C++ changes. Along the way a few new features were added and a bunch of bugs were fixed.

Far too much has changed for me to detail everything but here is a listing of some of the highlights.

• HTML files name do not change between runs so users can safely link to them.
• Namespaces are supported.
• Templates are supported.
• Warnings are generated for unresolved links (in addition to being reported in red).
• The development environment was moved to sourceforge.net.
• Inherited methods (-rptim) are reported as part of each class.
• Pre-processing directives are fully supported. Even complex expressions like this will work:

  #if defined(VENDOR1) && ( MAJOR_VERSION > 1 && LANG_CXX == 1 )
  extern void g_fct(string s);
  #elif defined(VENDOR2)
  extern "C" void g_fct(const char* s);
  #else
  extern void g_fct(const char* s);
  #endif

• The ccdoc.index.html file is not generated automatically. It has been replaced by the ccdoc.root.pkg.html for consistency with other packages.
• A hierarchical class summary is generated.
• The output format has changed. The new output format is much simpler and does not rely special GIF images.
• The output ordering has changed. All entities are now sorted. This change was made to accomodate the support for reporting inherited methods. The only exceptions to this are that packages and namespaces show up first followed by constructors and destructors.
• Ccdoc no longer attempts to expand wildcards on windows machines because that conflicts with attempts to specify * and ? characters in unix like shells.
• More control over color.
• The __ccdoc__ macro is now defined properly. You do not have to use the -D__ccdoc__=1 workaround from version 0.7a.
• Modified implementation to use STL and namespaces.
• Added regression tests.
• Fixed many bugs, among them:
  • Changed indent from <dir></dir> to <table></table> to improve display on different browsers. The <table></table> worked better than <blockquote></blockquote>.
  • Improved id recognition in C++ entities