ccdoc home page
CcDoc Users Guide for v08
Joe Linoff
$Revision: 1.10 $
$Date: 2003/02/27 05:02:53 $


Contents

? ^ < >
  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

Introduction

? ^ < >

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.


Using Ccdoc

? ^ < >

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:

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.
};

Use Case 23: How do I specify a link to an operator in the{@link ..} and @see directives?

There is a special case for operators. The example below shows how to specify both directives for an operator.

/**
 * This is the same as the {@link #operator== equals operator}
 * for this class.
 * @param obj The object to compare to for equality.
 * @returns True if they are equal or false otherwise.
 * @see #operator==
 */
bool is_equal(const Class& obj) const;

Note that there are no spaces between the operator keyword and the operator tokens.


Comment Syntax

? ^ < >

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.

Directive: /**< or /*!< .. */

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

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

Directive: /**@#-*/, /**@#+*/

Turns ccdoc token processing off and on. They are useful for turning off processing for tokens on a line. For whole lines, use the __ccdoc__ compiler pragma as shown in the example below:

// Turn off sections of code using __ccdoc__
#if !defined(__ccdoc__)
// Ignore stuff until the end
#endif


// Turn off scanning to avoid the @ token. This
// token is supported by this special purpose
// compiler but not by the C++ language.
int Foo ( /**@#-*/ @ /**@#+*/ x );

Directive: /**@#=<ch>*/

Insert a token into the ccdoc input stream to make parsing easier without affecting the source code. This directive is typically used to "fix" macro instantiations that are not terminated by semi-colons as shown in the following example:

This will confuse ccdoc.

#define M(a) a=1;
M
M
class XX;

This will not confuse ccdoc because we insert semi-colons.

#define M(a) a=1;
M /**@#=;*/
M /**@#=;*/
class XX;

Neither will this because we prep it out.

#define M(a) a=1;
#ifdef __ccdoc__
M
M
#endif
class XX;

Or this because we put in redundant semi-colons.

#define M(a) a=1;
M;
M;
class XX;

Directive: //@{, //@}

These directives designate the beginning and ending of C++ style ccdoc comment. This style avoids the problems of runaway comments. Here is an example of this style:

// ================================================
//@{                             <---- 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
// ================================================

Directive: //@-, ///<, //!<

The //@- directive is only supported in r26 or later.

The doxygen compatible forms: ///< and //!< are only supported in r37 or later.

Specifies the single line suffix C++ style comment form. This for is useful for abbreviated comments. Here is an example:

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

You can only specify a single line so directives other than {@link .. } and @link .. @endlink are not supported.

Directive: @@ <line>

Translate HTML special characters for creating code fragments.

Convert '<' to "&lt;" , '>' to "&gt;" and '&' to "&amp;". This is useful for inserting code fragments.

Here is an example of how you would use this directive in a comment:

/**
 * Here is an example of how to use this directive.
 *<pre>
 *@@ for(int i=0;i<10 && j>3;++i,--j) {
 *@@   cout << j << \" \" << i << endl;
 *@@ }
 *</dir>
 */
int dir_at_at();

Here is what the ccdoc output looks like. As you can see the <, > and && tokens are displayed correctly.


Directive: @author <name>

Specifies the author. To specify multiple authors add multiple directives as shown below.

/**
 * There are numerous authors.
 * @author Foo Bar
 * @author Spam Wombat
 */
int at_author();

Here is what the ccdoc output looks like.

If an author is not specified for a package, namespace, class, global function, global variable or global enum, an entry is generated to an \"unascribed\" author.

May folks like to include their e-mail address or links to their home page. The following example shows how to include e-mail links for the authors:

/**
 * Add a link to the authors e-mail:
 * @author <a href="mailto:joe@joelinoff.com">Joe Linoff</a>

 */
int at_author1();

Here is what it looks like in ccdoc:

Directive: @deprecated <description>

Specifies that this interface has been deprecated. You should specify what to use as an alternative. Here is an example of its use:

/**
 * Get something.
 * @deprecated Use this
 * @link Better::Function new function
 * to get better results.
 */
Something at_deprecated();

Here is what it looks like in ccdoc:

Note how the @link directive is embedded to create the link. Also note that the link is in red because ccdoc could not resolve it.

Directive: @exception <name> <description>

This directive was deprecated in favor of @throws in r23.

Directive: @link or @$ <entity> [<name>] .. [@endlink]

Generate a hyperlink to a ccdoc entity anywhere in the the code without generating an entry in the See section.

The @endlink directive is only supported in r37 or later for doxygen compatibility.

The <entity> is the ccdoc entity to link to. The <name> is the user name of the link. It can consist of one or more tokens. Leading white space is ignored.

If the name is not specified, the <entity> name is used.

The @endlink is optional. If it is not specified, the link specification terminates at the end of the line.

Here is an example of how it is used:

/**
 * This function is closely associated with
 * @link at_link2 the at_link1 function. @endlink
 */
void at_link1();
/**
 * This example shows how the &nbps;@link uses the
 * default name.
 * This function is closely associated with
 * @link at_link2 @endlink .
 */
void at_link2();

Here is what ccdoc documentation looks like:

Directive: @param <name> <description>

Describes a parameter to a function. There should be one @param directive for each argument.

Beware! Ccdoc does not verify that the parameters are valid so it is possible to input invalid parameters. Ccdoc does not verify that the parameter names are the same either as in the example above: aname should be x (or vice-versa).

The contents of an @param directive can span multiple lines. All lines following an @param directive are included until another ccdoc directive (other than @link and @@) is encountered.

The example below shows how to use this directive.

/**
 * This function does stuff.
 * @param name The name of the object. The description
 * will span multiple lines until another directive or
 * the end of the comment is found.
 * @param aname Another name.
 */
void at_param(const char* name,const char* x);

Here is what the ccdoc documentation looks like:

Directive: @pkg <path>

Specifies the name of the current package. All entities in the file from the directive onward are associated with the package. This pragma can be overridden from the command line by the -pkg switch.

There is a special package called -null- that can be used to to specify that the contents of a file are not associated with any package. This is typically used in the file (or files) that contain the package documentation. Typically these are not C++
files.

The example below shows how to define the package directive.

/**@pkg Stuff.Utils */

/**@pkg Stuff::Utils */

Dots '.' or double colons '::' are used to separate hierarchical sub-packages.

Package documentation is generated using the @pkgdoc directive as shown in the next entry.

Directive: @pkgdoc <path> [<url>]

Specifies that the current ccdoc comment is associated with a package NOT a C++ entity.

This directive can be used to define the documentation in the top package by specifying '@top' as the <name>. The old form: [ROOT] is still accepted.

Dots '.' or double colons '::' are used to separate hierarchical sub-packages.

If the <url> argument is specified, ccdoc uses that as the link. This is useful for inserting custom pages into the ccdoc document hierarchy but it puts a significant burden on the user to make sure that links to other ccdoc generated files are valid.

The following example shows how to document several packages.

 // This file is not part of any package.
 /**@pkg @null*/
 /**
  * This is the documentation for the top of
  * the documentation tree.
  * @author The Build Team
  * @version 1.1
  * @pkg @top
  */
 /**
  * This is the top level package for MyProject.
  *
  * It does lots of useful things and contains
  * many other packages.
  * @author Ms. MyProject
  * @version 1.0
  * @pkgdoc MyProject
  */
 /**
  * This package contains the I/O utilities for
  * MyProject.
  *
  * This is the detailed information about the
  * I/O utilities package.
  * @author Mr. IO_Utilities
  * @version 1.1
  * @pkgdoc MyProject::IO_Utilities
  */
 /**
  * This package contains the string utilities for
  * MyProject.
  *
  * This is the detailed information about the
  * string utilities package.
  * @author Mr. String_Utilities
  * @version 1.2
  * @pkgdoc MyProject.String_Utilities ../doc/String_Utilities.html

  */

It is important to note that the implicit top level package is implied for @pkgdoc paths.

Directive: @pkgdoctid <name>

This directive must be specified after @pkgdoc. If it isn't a warning will be generated and the directive will be ignored.

It allows you to redefine the pkgdoc title id. Normally when a package name is specified the title on the page is "package <name>". With this directive you can change the "package" string to anything you like.

It was added because some users would like to define different semantics for different packages, for example: some package might be subsystems, others might be modules and still others might really be packages. With this directive you can change the name in the generated HTML file to better reflect package semantics in your environment.

The example below shows how to define three packages: A, B and C. A is the top level, B and C are children. A will be reported as a "system", B will be reported as a "module" and C will be reported as a "subsystem".

/**
* @pkgdoc A ../doc/A.html
* @pkgdoctid system
*/
/**
* @pkgdoc A::B ../doc/A.B.html
* @pkgdoctid module
*/
/**
* @pkgdoc A::C ../doc/A.C.html
* @pkgdoctid subsystem
*/

The output HTML for these packages looks like this.

Note that I used the -rpthpc switch to generate this output.

Directive: @returns <description>

Describes the return value from a function. If there is no return value, do not use @returns. Ccdoc does not verify that you documented the return value correctly.

The contents of an @returns directive can span multiple lines. All lines following an @returns directive are included until another ccdoc directive (other than @link and @@) is encountered.

Here is an example of how it is used.

/**
 * Get the global value.
 * @returns The global value.
 * The value will always be between 1 and 100.
 */
static unsigned at_returns();

Here is what the ccdoc documentation looks like:

Directive: @see <entity> [<number>]

Associate an entity in the ccdoc database with the entity currently being described.

It tells ccdoc to generate a hyperlink to a named entity in the database. If there are multiple entities with the same name, as is the case with overloaded functions, specify the number of the one that you want ccdoc to use. The number should be between 0 and the number of duplicate entities minus 1. If no number is specified, the first occurrence is used.

There is an alternate form that allows the user to specify a url for the entity. This allows hyperlinks to objects that ccdoc doesn't know about. It is useful for adding links to documents.

There is another alternate form that allows the user to specify an entity in the current scope using a '#' prefix. This is convenient for describing method relations within a class.

Packages are not specified in the @see <entity> specification because they can be changed at run-time. Ccdoc searchs for all C++ entities that match the specification in all packages.

The example below shows how to use this directive.

/**
  * Generate three links, one to the class named Foo
  * the second to the second overloaded method
  * Spam in the Bar class and the third to a document
  * called wombat.
  * @see Foo
  * @see Spam::Bar
  * @see <a href=wombat.html>wombat</a>
  */
void at_see3();

Here is what the ccdoc documentation looks like:

There is a special case for operators. The example below shows how to specify an @see link to an operator.

/**
 * This is the same as the {@link #operator== equals operator}
 * for this class.
 * @param obj The object to compare to for equality.
 * @returns True if they are equal or false otherwise.
 * @see #operator==
 */
bool is_equal(const Class& obj) const;

Note that there are no spaces between the operator keyword and the operator tokens.

Directive: @since

This is entity has only been available since the specified version. Ccdoc does not impose any syntax requirements on the version string so you can use anything you want.

The example below shows how to use this directive.

class A {
public:
  /**
   * Get the name of the object.
   * @returns The name of the object as a "C" string.
   * @deprecated This function will go away in build 12.
   */
  const char* get_name() const;
  /**
   * Get the name of the object.
   * @param name The string to return the name to.s
   * @since v1.2 Built 2001/10/10.
   */
  void get_name(string& name) const;
};

Here is what the ccdoc documentation looks like:

Directive: @suffix

This is a suffix style comment, that is, it is attached to the preceding statement rather than the following statement as shown in the example below:

void at_suffix();
  //@{
  // This is the C++ style suffix comment
  // form that some folks have requested.
  // @suffix
  //@}

Here is what the ccdoc documentation looks like:

Directive: @throws <name> <description>

This directive is supported in r23 or later.

It is synonymous with @exception.

Specifies that this exception can be thrown by the method. If the <name> specifies a class in the ccdoc database, a hyperlink is added. The example below shows hows to specify this directive.

/**
 * This function does stuff.
 *
* Here is more detail about the stuff
* it does.
* @param name The name of the object.
* @returns The object.
* @throws Exception_NullParameter * Is thrown if name is NULL.
*/ Object* at_exception(string name);

Here is what it looks like:

As you can see in the example above, the contents of an @throws directive can span multiple lines. All lines following an @throws directive are included until another ccdoc directive (other than @link and @@) is encountered.

Directive: @todo <description>

This directive is supported in r27 or later.

Specifies that there are additional things things to be done to this interface or its implementation.

Directive: @version <id>

Specifies the version of the entity. If this directive is not specified for classes or packages, \"unknown\" is reported.

The example below shows how to use this directive:

//@{
// This function is global so it requires an author
// and a version.
// @author Foo
// @version 1.0
//@}
void at_version();

Here is what the ccdoc documentation looks like:


Directive: {@link <entity> <name>}

This directive is supported in r24 or later.

It is very similar to the @link directive except that it can be embedded inside comment lines. Like @link, it tells ccdoc to generate a hyperlink to a ccdoc entity. Unlike @link the arguments are not optional.

You must specify both the entity and the link name.

You must not embed white space in the '{@link' specification. For example, '{ @ link' is not valid.

Any number of link specifications are allowed on a single line.

Invalid {@link...} specifications are output as simple text.

The example below shows how it is used:

class A {
public:
  void fct1();
  void fct2();
  void fct3();
  /**
   * See {@link #fct1 x}, {@link #fct2 y} or {@link #fct3 x} to
   * figure out how this stuff works.
   */
  void fct4();
};

The <entity> is the ccdoc entity to link to. The <name> is the user name of the link. It can consist of one or more tokens. Leading white space is ignored.

Here is what the ccdoc documentation looks like:

As you can see, the in-line link names are x, y and z. They link to fct1, fct2 and fct3 respectively.

To generate references to other classes you would use the fully qualified path name as shown in the example below:

namespace N1 {
  namespace N2 {
    class A { ... };

  }
}

/**
 * This function uses global objects from
 * class {@link N1::N2::A A} to
 * do stuff.
 */
void fct();

There is a special case for operators. The example below shows how to specify an {@link ..} directive for an operator.

/**
 * This is the same as the {@link #operator== equals operator}
 * for this class.
 * @param obj The object to compare to for equality.
 * @returns True if they are equal or false otherwise.
 * @see #operator==
 */
bool is_equal(const Class& obj) const;

Note that there are no spaces between the operator keyword and the operator tokens.


Program Phases

? ^ < >

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.

Database Details

? ^ < >

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.


Release Notes

? ^ < >

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.