CcDoc
Version 0.7a
Last Updated: June 15, 1999

 Contents:
     Latest News
     Introduction
     Source Code Docs
     Downloading
     Running ccdoc
     Comment Syntax
     Release Notes
     Known Bugs
     Future Directions
     TODO List
     Other Documentation Systems
     Copyright Notice
     FAQ

Latest News

This is a new section that will be updated with the latest CcDoc news. The current plan is to update it whenever any significant events occur.

June 15, 1999

Re-Released v0.7a!

Tim Kemp found a serious bug (ID0101) that caused CcDoc to not handle wildcards correctly under Windows. This slipped through because of a bogus test. The test and the code have been fixed. Please re-download it today.

The new v0.7a bug tally is: Total=79 Fixed=61 Open=15 Closed=3. There were a lot of fixes. To see the release notes click here.

June 14, 1999

Released v0.7a!

The v0.7a bug tally is: Total=78 Fixed=60 Open=15 Closed=3. There were a lot of fixes. To see the release notes click here.

June 5, 1999

Work is still progressing well on v0.7a. The current bug tally is: Total=77 Fixed=56 Open=18 Closed=3. Some of these bugs are so significant that I will create the new release later this week or early next week, even if all of the enhancements I wanted for this release aren't completed.

May 27, 1999

Work is progressing well on v0.7a. The current bug tally is: Total=71 Fixed=46 Open=22 Closed=3. Some of these bugs are so significant that I will create the new release next week, even if all of the enhancements I wanted for this release aren't completed.

May 23, 1999

Work is progressing well on v0.7a. So far a number of bugs have been fixed and tested including:

I have added a summary report on the bug page to make it easier to figure out the status.

In addition, the HP port is well under way (I am doing it concurrently with Solaris and Windows development). I still don't have Linux box but as soon as I do, I will make sure that it ports there as well.

A couple of notes about the @see processing. It was really hosed. The code had been lifted from v0.6x without adequate testing. Now it has been thoroughly tested for all cases (including invalid references).

I have been very busy with other things so that work is going a bit more slowly than I would like. I may do an intermediate bug fix release soon if there is enough demand.

A number of new bug reports have come in. I want to thank everyone that took the time to report problems. If you don't see your bug there, please e-mail me again and will add it.

My CcDoc mailing was corrupted during my recent h/w conversion. Please be patient while I get it back on line. If you wish to make sure that you on the mailing list, it would be a good idea to resend your e-mail address.

Thank you for your patience.

May 6, 1999

Fixed some web page formatting problems, fixed example 1, updated the bug list and added the new flow.

May 5, 1999

I am finally back on track and have started implementing the v07a changes. Of course, I am already behind schedule. The current plan is to finish as soon as possible, perhaps in a month or so. I will update this space with status every week or so.

March 17, 1999

I am on vacation until mid-April. Please don't expect any e-mail responses until then.

March 10, 1999

I am behind schedule due to other pressing crises.

It looks like I won't be able to get back to work on v0.7a until early April which pushes out the release to around May 1, 1999.

February 19, 1999

Another enhancement was requested as described in ID0063 which is worthy of inclusion in v0.7a (because it is so straightforward).

February 17, 1999

A couple of new ideas have filtered in. One of the most important is ID0062 because it addresses run-time issues which I believe will be an issue when CcDoc supports the processing of implementation files. It will be incorporated as part of ID0058.

I am very busy right now and will not be able to start work on the v0.7a enhancements until later this month which means the release will slip a bit. I will report my estimated release schedule as soon as things quiet down a bit.

I want to thank everyone that sent in their ideas for enhancements.

Jan. 28, 1999

CcDoc v0.7 has had a chance to percolate into the field over the past month and a half. As a result, a large number of mail messages have been flowing in with bug reports and good ideas for enhancements. They have all been catalogued in the bug list (it is up to 58 now) and I have developed a plan for the v0.7a release.

The v0.7a will consist of the following changes:

Some of the others: ID0054 and ID0050 will be added as time permits.

For detailed information about the bugs go to the Known Bugs section or click here to go to the bug list.

The current plan is to release v0.7a sometime in early march.

In addition to the v0.7a planning, I have added a link to other C++ documentation generation systems so that folks will be aware of what is out there. This list was obtained by perusing Bjarne Stroustroups home page and following the C++ Programming Language link.

Dec. 7, 1998

Two verifiable bugs have been reported against v0.7, see the ID0049 and ID0050 for details. This information was sent out to the mailing list last week.

Nov. 29, 1998

CcDoc v0.7 was released and this page was re-written. Here are a couple of release highlights, more information can be found in the release notes:

Introduction

The CcDoc tool is a javadoc like tool that automatically generates web documentation from C++ programs by parsing the source file headers. It was written because I write code in both Java and C++ and wanted a consistent interface for both. I tried very hard to stay true to the javadoc syntax and tool flow but, because of language differences I was forced to change (or add) a few things.

With this tool you do not have to explicitly specify classes, methods or variables, the parser figures them out which means that it works whether or not you have embedded comments. This means that it can be run over code with a different comment style to build basic web pages that document classes in a set of packages. You can add documentation later.

One unique aspect of CcDoc is that it tries to understand the program before pre-processing. This allows you to comment macro definitions but makes the parsing problem much harder.

If you are interested in being added to my CcDoc mailing list, please send me e-mail by clicking here.

To see the CcDoc code documentation click here.

Cost

This tool is free software with no express or implied warranty. You are free to copy and modify it but you must keep the copyright and permissions notices intact.

Starting with v0.8, ccdoc will be provided as shareware for $20.00 per copy. The source code will still be provided as part of the release and you can still download the program and try it at no cost.

The only difference is that I am asking that you send me a small fee if you find the program useful so that I can continue to develop and support it.

I am still developing and maintaining the program on a PC running Windows 95 (4.000.950a) with a 90MHz Pentium, 48MB of memory, and two 540MB hard drives. Not exactly state of the art. In future I would like to upgrade my PC to one that has a working CD-ROM drive and get a Linux machine so that I can port to it.

Support Options

I have received a number of e-mails asking about what support options are available so I will present the range of options after I have said a few things.

My intent here is NOT to make money but to encourage everyone to use the free internet resources available for support.

The last option is presented because several companies have contacted me about an option that they can pay for.

Here they are in my order of preference:

 Option

Cost

Description

 1

 FREE

 Support the program at your site using the source code that is provided.

I have received e-mail from more than 200 folks who are using ccdoc and can be contacted through various news groups or from my web page.

This means that there is a community of folks out there who use and understand the program.

 2

 FREE

 Send me suggestions via e-mail which will be categorized and prioritized based on my understanding of the requirements of the user community.

3

 $$$$

 Contact me about consulting options or a support contract.

Click here to return to the top.

Downloading

The CcDoc distribution has been simplified. There are now two packages available for downloading. They are shown in the table below. Clicking on them will invoke the download mechanism.

 Name

Operating System

 Format
 ccdoc_v07a bin_taz.exe The binary distribution for Solaris 5.6, HP UX 10, and Windows 95/98/NT. It is about 530K.  tar, gzip
 ccdoc_v07a src_taz.exe The source code distribution along with the binaries. It is about 834K.  tar, gzip

Notice that although the format of the package is a gzip'ed tar file, the file extension is ".exe". This is because my ISP does not provide anonymous FTP service. Because of this, I must use an http URL reference in the download anchors. Unfortunately, many URL parsers do not yet recognize the ".taz" extension but they do recognize the ".exe" extension as binary and don't munge it. Once you download the archive you must rename with a .taz extension on all platorms.

The binary distribution directory structure looks like this:

ccdoc_v07a +--> bin +--> hp  +--> ccdoc.exe [HP]
           |        |        |
           |        |        +--> ctf_merge.pl
           |        |
           |        +--> sol +--> ccdoc.exe [Solaris]
           |        |        |
           |        |        +--> ctf_merge.pl
           |        |
           |        +--> win +--> ccdoc.exe [Windows]
           |                 |
           |                 +--> ctf_merge.pl
           |
           +--> doc +--> autodoc
                    |
                    +--> images

The HTML based documentation is under the doc directory and the associated GIFs are under the doc/images directory.

The autodoc directory contains the files generated for the CcDoc source code documentation.

The source distribution directory structure looks like this:

ccdoc_v07a +--> doc +--> autodoc
           |        |
           |        +--> images
           |
           +--> src +--> ccdoc --+--> src
                    |            |
                    |            +--> test
                    |
                    +--> libjdl -+--> src
                    |            |
                    |            +--> test
                    +--> tools

The src directories contain the source code and the test directories contain the regression tests.

The tools directory contains miscellaneous tools for building CcDoc.

To learn how to unpack the binary distribution of CcDoc under Windows click here.

To learn how to unpack the binary distribution of CcDoc under Solaris click here.

Unpacking Under Windows

This section shows how to unpack and install the archive under Windows. It assumes that you were able to download the archive to C:\CcDoc. You will need winzip to run this example. It is a cool program and well worth the expense.

After the program is downloaded, Windows Explorer will look something like this:

Change the name as follows:

When you do this, a warning dialogue will pop up that asks if you really want to do this:

Answer yes here, then double click the .taz file and WinZip will pop up:

Choose the extract option and ccdoc is now available in C:\ccdoc\v07\bin\win\ccdoc.exe.

Unpacking Under Solaris

This section describes how to unpack the distribution under Solaris. It assumes that you were able to download the archive to ~/tmp. You will need tar and gzip to unpack distribution. If tar or gzip aren't available in your environment, you can download them from gnu (ftp://prep.ai.mit.edu/pub/gnu).

The steps are shown below:

% cd ~/tmp
% mv ccdoc_v07_bin_taz.exe ccdoc_v07.taz
% gunzip ccdoc_v07.taz
% tar xvf ccdoc_v07.tar

The ccdoc program will be available in ~/tmp/ccdoc/v07/bin/sol/ccdoc.exe.

Click here to return to the top.

Running Ccdoc

The following four examples show how to run ccdoc under NT and Solaris for two simple cases. Following that there is a complete description of the switches and environment variables.

Example 1: Documenting a Single Package under NT

This example assumes that you are generating the documentation for single program (or library) in a subdirectory of the development directory called doc.

C:> ccdoc -imageurl images/ -srcurl src/ -pkg myprog -html doc\ -index *.h

Example 2: Documentating Multiple Packages under NT

This example assumes that you are generating the documentation for a group of programs and libraries, and that the documentation is going into a directory called C:\Web.

C:> cd \msdev\projects\dostuff
C:> rem ************************************************
C:> rem * Create the package documentation.
C:> rem ************************************************
C:> ccdoc -ctf typical.ctf -log run.log -pkg pkg.libjdl libjdl\src\*.h
C:> ccdoc -ctf typical.ctf -log run.log -pkg pkg.ccdoc ccdoc\src\*.h

C:> rem ************************************************
C:> rem * Create the ROOT documentation.
C:> rem ************************************************
C:> ccdoc -ctf typical.ctf -log run.log -pkg ccdoc ccdoc.pkg

C:> rem ************************************************
C:> rem * Create the INDEX.
C:> rem ************************************************
C:> ccdoc -ctf typical.ctf -index

C:> rem ************************************************
C:> rem * Create the HTML.
C:> rem ************************************************
C:> ccdoc -ctf typical.ctf -html doc\ -imgurl doc\ -srcurl doc\src\ -trailer custom.html

Example 3: Documentating a Single Package under Solaris

This example assumes that you are generating the documentation for single program (or library) in a subdirectory of the development directory called doc.

% ccdoc -imageurl images/ -srcurl src/ -pkg myprog -html doc/ -index doc/ *.h

Example 4: Documenting Multiple Packages under Solaris

This example assumes that you are generating the documentation for a group of programs and libraries, and that the documentation is going into a directory called ~/web.

% cd ~/projects/dostuff
% # ************************************************
% # * Create the package documentation.
% # ************************************************
% ccdoc -ctf typical.ctf -log run.log -pkg pkg.libjdl libjdl/src/*.h
% ccdoc -ctf typical.ctf -log run.log -pkg pkg.ccdoc ccdoc/src/*.h
  
% # ************************************************
% # * Create the ROOT documentation.
% # ************************************************
% ccdoc -ctf typical.ctf -log run.log -pkg ccdoc ccdoc.pkg
  
% # ************************************************
% # * Create the INDEX.
% # ************************************************
% ccdoc -ctf typical.ctf -index
  
% # ************************************************
% # * Create the HTML.
% # ************************************************
% ccdoc -ctf typical.ctf -html doc/ -imgurl doc/ -srcurl doc/src/ -trailer custom.html

Generic Switches

These switches can be used in all phases.

Generic Switches

 Switches

Description

 
-ctf <file>
 The name of the CTF (CcDoc Token Format) file. 
-h
 On-line help. 
-log <file>
 Specify the name of the log file. When the log file is specified messages will be sent to the screen and to the log file simultaneously. It is similar to using the tee command under unix. 
-[no]v
 Verbose mode. The default is off. 
-[no]warn
 Turn warnings on or off. The default is on.

Phase 1 Switches

Phase 1 processing is the parsing phase, this is where all of the input files are converted to an abstract parse tree. This phase assigns language items to specific packages. The parse tree information is written to the CTF file.

Phase 1 Switches

 Switches

Description

 
-D<name>
 Define a macro. The macro __ccdoc__ is predefined. Unlike the C++ pre-process, values cannot be assigned to macros. Note that there is no space between the switch and the name. 
-pkg <name>
 The name of the package which this contents of this file are associated. Package names can be hierarchical. Hierarchical parts are separated by dots. The following is an example of a hierarchical name: AA.BB.CC. 
-U<name>
 Undefine a macro. You can use this switch to undefined __ccdoc__.

Phase 2 Switches

Phase 2 processing is the indexing phase, this is where all nodes in the abstract parse tree are indexed. The index information is written to the CTF file.

Phase 2 Switches

 Switches

Description

 
-index
 Index the contents of the parse tree.

Phase 3 Switches

Phase 3 processing is the HTML generation phase. During this phase the abstract parse tree and the index information is read and processed to create HTML documentation.

Phase 3 Switches

 Switches

Description

 
-bg <color>
 The background color. The default is white (#FFFFFF). 
-header <file>
 The HTML used for the customized header.  
-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. 
-fg <color>
 The foreground color. The default is black (#000000). 
-[no]globals
 Report globally scoped items. Default is on.  
-[no]gpi 
 Group the pkg index items by type. The default is on.  
-imageurl <URL> 


-imgurl <URL>
 The URL that describes of the GIF images. It is used a prefix so you must include the directory suffix.  
-[no]locals 
 Report locally scoped items. Default is on.  
-[no]macros
 Report macros. Default is off.  
-[no]private  
 Report private items. Default is off.  
-[no]protected 
 Report protected items. Default is on.  
-[no]public 
 Report public items. Default is on.  
-root <name> 
 The alternate name for the [ROOT] node. This is the node that always shows up as the root of the package tree. 
-rooturl <URL> 
 The hyperlink for [ROOT]. Setting this allows the ccdoc generated HTML to seamlessly integrate to a higher level document. 
-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 
 Report typedefs. Default is on. 

Environment Variables

There are a number of environment variables that can be used during development and debugging. They are listed in the table below.

Environment Variables

 Switches

Description

 
CCDOC_LEXER_DEBUG
 Turn on lexer debugging. 
CCDOC_LEXER_RC
 Specifies an alternate resource file that the user can use to define their own reserved words and keywords.  
CCDOC_PHASE3_DEBUG
 Turn on phase 3 verbose mode.  
CCDOC_PHASE3_TREE_ANCHORS_OFF
 Turn off anchors for tree nodes to make visual debugging easier.  
CCDOC_PARSER_DEBUG 
 Turn on parser debugging.  
CCDOC_PREP_DEBUG 
 Turn on pre-processor debugging.  
CCDOC_PREP_SAVE_DEBUG 
 Don't delete the pre-processor temporary files (<file>-PP). 
CCDOC_STRINGMAP_DEBUG
 Turn on string map debugging. This is very useful for folks that want to interface directly to the CTF file because it associates the string values with their ids in the parse tree. It is not used by default because it takes up too much disk space.  
CCDOC_VERBOSE
 Turn on verbose mode. This the same as using the -v switch on the command line. 

Click here to return to the top.

Comment Syntax

CcDoc recognizes comments blocks that occur before C++ constructs.

A comment block starts with a '/**' and ends with a '*/'. Each line in the comment block optionally starts with an asterisk '*'. The second line of a comment block and all subsequent lines up to the first blank line contain the summary description of the block.

Comments are made up of three basic entities: the brief description, the full description and the directives. The basic format of a comment is shown below:

/**
 * <brief description>
 *
 * <full description>
 * <directive>
 * <directive>
 * .
 * .
 * <directive>
 */

A shorthand form of the comments is also available:

/** <brief description> */

The <brief description> is the information that shows up as the entity descriptor on the summary page. It is separated from the <full description> by a blank line.

The <full description> describes the entity and can include the HTML constructs.

The <directive> entries start with an @ sign and are the first things (after the optional leading asterisk) on the line. A summary of the available directives is shown below:

Ccdoc Directives

 Directive (Tag)

Description
/**@#-*/
/**@#+*/		 These two tags are used to turn off token parsing in the CcDoc preprocessor. Anything that appears between these two directives is ignored. They are not recursive.

These pragmas are useful for removing sections of code that you do not want CcDoc to see. For example, many folks use include guards that look something like this:

#ifndef _this_include_file
#define _this_include_file
.
.
#endif

Unfortunately, CcDoc thinks this is of interest (in -macros mode) which generates lots of useless items. You can use these directives to tell CcDoc to ignore them as follows:

#ifndef _this_include_file
/**@#-*/
#define _this_include_file
/**@#-*/
.
.
#endif
@@ Special tag that tells the comment parser to read the rest of the line and convert it to an HTML form that the HTML processor will not try to interpret it.

It is useful for documenting the keywords and such in header files. The only translation done on the line is braces are converted to HTML constructs, that is < becomes &lt; and > become &gt;.

This is extremely used for embedding code fragments in the comments. 
@$ <name> Hyperlinks to other classes or methods. This
very similar to @see but it can be used anywhere
and the @see # mode is not supported.

It can be used as follows:

/**
* This is a brief description, see the
* related class
* @$ Foo
*
* This is the full description.
*@author Spam
*@version $Id:$
*/
@author <name> Specifies the author. For multiple authors the original author should appear first. 
@exception <name> Specifies that this exception can be thrown by this method.
@exceptions <name> Same as @exception. 
@param <name> <description> Describes a parameter to the method. There is one @param statement for each parameter. 
@pkg <name> The name of the current package. This comment has a special form: /**@pkg <name>*/. It can appear once in a file as a standalone comment to describe the package with which all elements of the file are associated. This directive can be overidden by the -pkg switch on the command line.

There is a special package called [NULL] that can be used to say that the contents of the specified file are not part of any package. This special package is used for files that contain only pkg documentation (see the @pkgdoc directive).
@pkgdoc <name> The comment form in which this appears is not associated with any C++ element. It is only associated with a package. This is used to document package pages in the hierarchical tree.
@return <description> Describes the return value from the method. If there is no return value, do not use the @return. 
@returns <description> Same as @return. This is the one that I prefer. 
@see <name> Hyperlinks to other classes or structs. Ccdoc will automatically try to create hyperlink unless the first character is a '<' or a '@'. If the first character is a '<', the parser will assume that you have manually created the hyperlink. If the first character is a '@', the parser will not try to translate the following text. 
You can also specify methods within a class by separating the method name from the class name using a hash mark '#' or a '::'.
For example, if you wish to add a reference to the CJdlString::Compare method you would enter "* @see CJdlString::Compare" in the comment.
To reference a method in the local class you must always use the hashmark as follows: "* @see #LocalMethod". 
To reference another class simply specify the class name as follows: "* @see OtherClass". 
@source <file> Specify the source file that this class came from. This is a departure from javadoc because the java language guarantees the physical location of a class. 

You do not need to specify this because CcDoc automatically inserts source information for classes and structs.
@version <id> Specifies the version of the class. I usually use the RCS id: $ID:$. 

Several use case scenarios are shown below:

Use Case 1: The Class comment structure.

In this example, the <brief description> is in red, the <full description> is in blue and the <keywords> are in magenta.

/**
 * Graph class. This is very similar to but more 
 * general than the 
 *$ CTree
 * class. 
 *
 * The graph class object contains a complete, directed graph.
 * To use it you would do the following:
 * <pre><dir>
 *@@ CGraph* graph = new CGraph("my graph");
 *@@ graph->AddNode("farley");
 *@@ graph->AddNode("henderson");
 *@@ graph->Connect("farley","henderson");
 * </pre></dir>
 *
 * It should be used for all directed graph applications.
 * @author Farley Henderson
 * @version $Id:$
 * @see CGraphNode
 * @see CGraphEdge
 */
class CGraph { ... };

Use Case 2: A brief method description.

/** Default constructor. */


CGraph();

Use Case 3: A complex method description.

In this example, the <brief description> is in red, the <full description> is in blue and the <keywords> are in magenta.

/**
 * Create a directed edge between two nodes.
 *
 * This method creates a directed edge between two nodes
 * in the graph.
 *
 * The example below shows how to create a fully connected
 * graph.
 * <pre></dir>
 *@@ {for(int i=0;i<graph->GetNumNodes();i++) {
 *@@   {for(int j=0;j<graph->GetNumNodes();j++) {
 *@@     if(i!=j) {
 *@@       CGraphNode* ndi = graph->GetNode(i);
 *@@       CGraphNode* ndj = graph->GetNode(j);
 *@@       CGraphEdge* edge = graph->Connect(ndi,ndj);
 *@@     }
 *@@   }}
 *@@ }}
 * </pre></dir>
 * @param node1 The from node.
 *              If the node is NULL, the method does not create an edge.
 * @param node2 The to node.
 *              If the node is NULL, the method does not create an edge.
 * @returns The edge object.
 */

You can embed HTML directly into the comments. The blank line translates to a <p> directive. The <pre></pre> and <dir></dir> directives are very useful for documenting code segments.

Sometimes embedded code into a comment can cause problems because the language constructs conflict with the HTML syntax. Consider the following example:

/**
 * This will cause HTML errors.
 *
 * Code example:
 * <pre><dir>
 * {for(int i=0;i<10;i++) {
 *   if(i<foo || i>foo) {
 *     .
 *     .
 *   }
 * }}
 * </pre></dir>
 */

The ccdoc comment parser passes the code directly through the HTML. When you attempt to load this page, the HTML parser can't figure out which directive "<foo || i>" corresponds to and tosses it out resulting in some strange looking code. To work around this problem you need to use the @@ directive. This tells ccdoc to replace < and > with &lt; and &gt;. Using this directive you would recode the above example as.

/**
 * This will not cause HTML errors.
 *
 * Code example:
 * <pre><dir>
 *@@ {for(int i=0;i<10;i++) {
 *@@   if(i<foo || i>foo) {
 *@@     .
 *@@     .
 *@@   }
 *@@ }}
 * </pre></dir>
 */

Use Case 4: Specifying a package.

This example shows how to specify a package id for a file. This package is hierarchical.

/**@pkg mystuff.utils */
/** Do a string copy using my stuff. */
char* mystrdup(const char*);

Use Case 5: Creating package documentation for a system.

This use case shows you how to create a package documentation file. It uses the [NULL] package name to tell CcDoc that this file only contains pkgdoc documentation.

// Tell CcDoc that this file contains only pkgdoc documentation.
/**@pkg [NULL] */

// The -root <name> switch used to convert [ROOT] to MY_TOP.

/**
 * This is the root node.
 * @author FooBar
 * @version 1.0
 * @pkgdoc [ROOT]
 */

/**
 * Utilities. This is a collection of useful utilities.
 * @author FooBar
 * @version 1.1
 * @pkgdoc Utilities
 */

Use Case 6: The commands I used to create the CcDoc documentation

This use case shows you how I created the CcDoc documentation. The steps are as follows:

  1. I created a package documentation file called ccdoc.pkg
  2. I created a package trailer file called ccdoc.trailer
  3. I generated the documentation in three phases using ccdoc.

Here is the ccdoc.pkg file:

// Top level documentation for ccdoc program.

/**@pkg [NULL]*/
/**
 * CcDoc source code documentation.
 *
 * To see information on the switches click on
 * the root node (Packages) below.
 *
 * @author Joe Linoff
 * @version 0.7 alpha
 * @pkgdoc [ROOT]
 */

Here is the ccdoc.trailer file:

<center>
<font size=-1>
<p>
This documentation was generated automatically by ccdoc v0.7.
<br>
Click here <a href=mailto:jdl@xilinx.com>here</a> to submit a bug
report or feature request to the author.
</font>
</center>

Here are the commands used to generate the documentation:

% # Phase 0: Initialize
% rm -f ccdoc.ctf
% # Phase 1: Create the parse tree nodes.
% ccdoc.exe -DJDL_DEFINE_LOCAL_TYPES -pkg ccdoc ccdoc/src/*.h ccdoc/src/main.cpp
% ccdoc.exe -DJDL_DEFINE_LOCAL_TYPES -pkg libjdl libjdl/src/*.h
% ccdoc.exe ccdoc/doc/ccdoc.pkg
% # Phase 2: Create the index.
% ccdoc.exe -index
% # Phase 3: Create the HTML
% ccdoc.exe \
    -macros \
    -rooturl index.html \
    -root Packages \
    -html doc/ \
    -srcurl doc/src/ / \
    -trailer ccdoc/doc/ccdoc.trailer \
    -imageurl images/

Click here to return to the top.

Release Notes

v0.7a

In this version the release notes were generated automatically. Click here to see them.

v0.7

v0.6a

Work on version 0.7 is taking longer than expected because it is a major release that changes the internal flow to make it easier for folks to add their own formatting styles. As a result, I have decided to create the v0.6a interim release with a few of the new pragma directives that originally intended to add in the 0.7 release.

Pragma directives allow programmers to have meta-control over the ccdoc lexer. They have the following syntax:

/**@#<directive>*/

Currently there are three pragma directives defined:

 Pragma Directive

Description

 
 /**@#-*/
 Off pragma. This tells the lexer to ignore all characters until it encounters the on pragma. 
 /**@#+*/
 On pragma. This is used to re-enable scanning after an off pragma. 
 /**@#=<char>*/
 Push <char> onto the input stack so that this is the next input character to the lexer.

Note that each directive stands alone and that there are no spaces.

The examples below show how to use these pragmas.

Example 1: Ignore duplicate definitions of a method.

In previous versions of ccdoc, duplicate definitions of methods would be generated when the programmer was using a C++ pragma to vary the method declarations for different platforms as shown below:

// This would cause two method declarations
// to be generated.
#ifdef NT
DLL_EXPORT void GlobalFct(long val);
#else
void GlobalFct(long val);
#endif

By using the ccdoc off and on pragmas, you can now force only one definition to be considered as shown below.

// This would cause two method declarations
// to be generated.
#ifdef NT
/**@-*/
DLL_EXPORT void GlobalFct(long val);
/**@+*/
#else
void GlobalFct(long val);
#endif

Example 2: Handle implicit semi-colons.

Previous versions of ccdoc got very confused when a macro definition was terminated by a comma and the programmer did not use a semi-colon to terminate the instantiation as shown below:

// This really confuses ccdoc.
#define PRINTLN(arg) cout << (arg) << endl;
PRINTLN("Hello, world!")
PRINTLN("foo")
PRINTLN("bar")
struct Globals {int i;};

To work around this you can use the ccdoc push pragma to insert a semi-colon onto the input stream after the macro instantations as shown below.

// This does not confuse ccdoc.
#define PRINTLN(arg) cout << (arg) << endl;
PRINTLN("Hello, world!") /**@=;*/
PRINTLN("foo") /**@=;*/
PRINTLN("bar") /**@=;*/
struct Globals {int i;};

Of course, in this case, you could just add the comma's directly.

Click here to return to the top.

Known Bugs

Listed below are the bugs and enhancements that have been reported for v0.6 and later.

Please note that many of the same bugs have been reported by different people so you may not find your name associated with the bug. If that is a problem, send me e-mail and I will add your name.

I want to thank everyone has reported bugs and enhancement ideas to me. Overall, the quality of the help has been outstanding and is really helping me get higher quality versions out.

The list has become so large that I have moved it here.

Reporting New Bugs, Comments or Suggestions

Please report bugs, comments or suggestions to me by clicking here.

The format for the bug report should look something like this: 

    Reported By: <Your Name>
    Reported On: <The Date>
    Found In:    <The CcDoc Version (currently v0.7)>
    Description:
      <Your description of the bug.>

All comments and suggestions are welcome.

Click here to return to the top.

Future Directions

This section discusses how I plan to evolve ccdoc.

The current plan is to modify ccdoc so it operates in stages.

  1. Convert the C++ interface code and the comment code to CTF.
  2. Convert the C++ implementation code comments that are associated with known methods to CTF.
    This might need to happen after the cross reference phase.
  3. Generate cross references in the intermediate format.
  4. Generate the HTML pages.

The idea behind this approach is that folks could put in their own formatting tools and generate whatever they like from the intermediate form. This concept is illustrated in the figure below.

The ccdoc token format (CTF) is an easily parseable ASCII format. My intention is to easily support 3rd party helpers built in perl or java.

Click here to return to the top.

TODO List (as of 1999/06/12)

  1. Begin work on v0.7b.

Click here to return to the top.

Copyright Notice

Copyright (C) 1998, 1999 by Joe Linoff
All rights reserved.

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

Comments and suggestions are always welcome.

Click here to return to the top.