ccdoc home page
Introduction
$Revision: 1.2 $
$Date: 2003/02/26 18:45:42 $
Joe Linoff

History and Design Goals

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.

This tool was originally written by me, Joe Linoff, in 1996 and has been updated as often as necessary to fix bugs or keep up with new language features.

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

If you are interested in being added to my CcDoc mailing list, please send me e-mail by clicking here. The mailing list is not disclosed to anyone (other than the other participants). I only use it to send out infrequent status updates.

The ccdoc web site provides a number of resources to help you use this tool. If you want to document some code, the best place to start is the next section. After that take a look at the best practices document and the users guide.

If you want to port ccdoc to another platform, take a look at the porting guide.

Usage Introduction

This section briefly introduces how to use ccdoc for a very simple "Hello, world!" type example. This will give you a general flavor of how this tool works but first here is a screen shot showing the flow from the source file (in the upper left) to the HTML documentation (on the right).

Figure 1. Overview Screen Shot

 

In this example you are a programmer who is developing a package that will be used by other programmers. The other programmers want to know how to use your package but don't want (or need) to understand the source code. Your charter is to produce documentation that can be used by your clients but you have the challenge of making sure it describes how you expect them to use the package and you have to keep it up to date as the package changes over time.

Your package is called the hello_world package. It provides a single function that prints "Hello, world!" to cout. Shown below is your source directory setup:

Figure 2. The example directory structure.
 
hello_world --+--> export ------> hello_world.h
              |
              +--> src -----+---> Makefile
                            +---> hello_world.cc

The initial version of the hello_world.h file looks like this:

Figure 3. hello_world.h (no comments)
 
#ifndef hello_world_h
#define hello_world_h

namespace hello_world {
   void hi(ostream& os = cout);
}

#endif

You now decide that you want to use ccdoc, so the first step is to go to the ccdoc web site and download the executable. The executable is always called ccdoc.exe and the only thing that you need to do to use it is install it somewhere where your PATH variable can find it. To uninstall ccdoc all you have to do is delete the executable. This example assumes that ccdoc.exe has already been installed.

Here is how you could update the header file with ccdoc comments:

Figure 4. hello_world.h (with ccdoc comments)
 
/**
 * Copyright 2003 (c)
 * Dreamers Incorporated is a company that sells software
 * packages that make programming easier.
 * Our premier software package is the hello_world library
 * that allows programmers in all walks of life to generate
 * the hello world output in their own custom programs.
 * @author I.M. Adreamer
 * @version $Id: introduction.htm,v 1.2 2003/02/26 18:45:42 jlinoff Exp $
 * @pkgdoc @root
 */
#ifndef hello_world_h
#define hello_world_h

/**
 * The hello_world namespace associates all of
 * the services related to the hello_world package.
 * This package exists to help programmers all over
 * the world output the standard "Hello, world!"
 * with minimal effort.
 * @author I.M. Adreamer
 * @version $Id: introduction.htm,v 1.2 2003/02/26 18:45:42 jlinoff Exp $
 */
namespace hello_world {
   /**
    * Say "Hello, world!" to the world.
    * The example below shows how to use this function:
    *<blockquote>
    *<pre>
    *@@ #include "hello_world.h"
    *@@ int main(int,char**) {
    *@@    hello_world::hi();
    *@@ }
    *</pre>
    *</blockquote>
    * @param os The output stream.
    * @author I.M. Aprogrammer
    * @version $Id: introduction.htm,v 1.2 2003/02/26 18:45:42 jlinoff Exp $
    */
   void hi(ostream& os = cout);
}

#endif

As you can see, anyone reading this header file would know several important things:

  1. Who the author of the package is.
  2. What the version is.
  3. What the intent of the package is.
  4. How to use the hi() function.

To create the associated web documentation you would create another directory that was accessible from the web (it will be called htdocs in this example) and run ccdoc to create the documentation files in that directory. As shown below, the ccdoc command was added to the make file so that the web based documentation is automatically updated each time the header file is changed.

Figure 5. Makefile target for ccdoc
 
# Create the ccdoc documentation if the header file changed.
../htdocs/ccdoc.db : ../htdocs ../export/hello_world.h
        rm -f ../htdocs/*
        ccdoc.exe -db ../htdocs/ccdoc.db \
                ../export/hello_world.h \
                -index \
                -root dreamers_inc \
                -rootfile ../htdocs/index.html \
                -html ../htdocs/
        
# Create the htdocs directory, if necessary.
../htdocs : ; @mkdir $@

When this make target is run, the htdocs directory is created with the following files:

Figure 6. Generated Documentation Files
 
ccdoc.class_summary.html
ccdoc.db
ccdoc.dreamers_inc.hello_world.hi.void.hi.-28.ostream.-26.os.-3d.cout.-29.fct.html
ccdoc.dreamers_inc.hello_world.nsp.html
index.html

Here is what the documentation looks like from a browser:

Figure 7. htdocs/index.html

When you click on the hello_world namespace you will see this page:

Figure 8. The hello_world namespace documentation

When you click on the hi function you will see this page.

Figure 9. The hi() function documentation

As this example demonstrates, ccdoc enables you to create web documentation to describe your interface. It also allows you to tie that documentation in with your existing site documentation.

What this example doesn't show are the many user configurable options that you can use to customize the generated documentation. For example, you might want to change the trailer so that it references your company and allows clients to submit requests to you (not me). This is done using the -trailer switch. For more information about this switch and everything else that ccdoc has to offer, see the users guide. For more style and usage information take a look at the best practices document

$Id: introduction.htm,v 1.2 2003/02/26 18:45:42 jlinoff Exp $