1. How do I install ccdoc?
2. How do I uninstall ccdoc?
3. How can I determine which version of ccdoc I am using?
4. How can I tell ccdoc to ignore include guards?
5. Can I add documentation after the entity rather than before?
6. What do I need to do to make my comments compatible with both doxygen and ccdoc?
7. What is the difference between ccdoc and doxygen?
8. Why is the on-line help so extensive?
9. Do you have an example batch file for running ccdoc under Windows that I can use as a template?
10. How do I log an issue?

• cp ccdoc.exe /usr/local/bin/ccdoc

Here is an example install on windows:

• copy ccdoc.exe c:\windows\system32\ccdoc.exe

% ccdoc -version
ccdoc v08r38 2003/02/24 bin_opt_msvc_MSWin32-x86-multi-thread-4.0

ccdoc v08r38 2003/02/24 bin_opt_msvc_MSWin32-x86-multi-thread-4.0
^     ^  ^   ^          ^
|     |  |   |          +--- The compiler, platform and build type.
|     |  |   +-------------- The release date.
|     |  +------------------ The revision (minor version).
|     +--------------------- The version.
+--------------------------- The program identifier.

• A _h or _H suffix.
• A _hh or _HH suffix.
• A _include or _INCLUDE suffix.
• A _included_ or _INCLUDED_ suffix.
• A include_ or INCLUDE_ prefix.
• A _dll or _DLL suffix.
• A dll_ or DLL_ prefix.

More patterns can be added if users request it.

struct Simple {
  int m_x1; //@- The x1 field.
  int m_x2; ///< The x2 field.
  int m_x3; //!< The x3 field.
  int m_x4; /**
             * The x4 field.
             * I want to say a lot about this one.
             * @suffix
             */
  int m_x5; /**<
             * The x5 field.
             * I want to say a lot about this one.
             */
  int m_x6; /*!<
             * The x6 field.
             * I want to say a lot about this one.
             */
};

I prefer the ///< and //!< because they are doxygen compatible. The //@- and @suffix are historical.

Date: 2003/02/23

I am not an expert on doxygen but here are a couple of things that have been pointed out me by users:

1. Make sure that you use the doxygen comment style for suffix comments and single line comments.
2. Use @link @endlink instead of {@link .. }.
3. Don't use doxygen style comment grouping. The syntax is the same as the ccdoc syntax for C++ style single line comments.
4. The HTML <blockquote> construct is not supported by doxygen so use it warily.
5. Don't use the '@@' ccdoc construct. It doesn't translate well to doxygen.

I will try to continue to enhance ccdoc to work smoothly with doxygen. Any suggestions would be greatly appreciated.

Three examples are presented below to show what works and what doesn't.

Example 1: Embedded links.

The example below shows two versions of the same comment. The first one will work with ccdoc and doxygen. The second one will only work with ccdoc because it uses the javadoc style {@link} directive which isn't supported by doxygen.

// Works with doxygen and ccdoc.
/**
 * This function does stuff.
 * This function is related to @link other_function @end_link .
 * @author A. Programmer.
 * @version 1.0
 */
void this_function();


/**
 * This function does stuff.
 * This function is related to {@link other_function} .
 * @author A. Programmer.
 * @version 1.0
 */
void this_function();

Example 2: Suffix style multi-line comments

The example below shows two versions of the same comment. The first one will
work with ccdoc and doxygen. The second one will only work with ccdoc because
it uses the @suffix directive.

// Works with doxygen and ccdoc. Note that /*!< is also supported.
void this_function();
  /**<
   * This function does stuff.
   * This function is related to @link other_function @end_link .
   * @author A. Programmer.
   * @version 1.0
   */

void this_function();
  /**
   * This function does stuff.
   * This function is related to @link other_function @end_link .
   * @author A. Programmer.
   * @version 1.0
   * @suffix
   */

Example 3: Suffix style single-line comments

The example below shows two versions of the same comment. The first one will
work with ccdoc and doxygen. The second one will only work with ccdoc because
it uses the //@- suffix comment type.

// Works with doxygen and ccdoc. Note that //!< is also supported.
void this_function();
  ///< This function does stuff.

void this_function();
  //@- This function does stuff.

Date: 2003/02/23

I am not an expert on doxygen but here is my understanding of the differences between the two.

Ccdoc is an interface documentation tool. It is meant to be used by package developers who want to generate documentation for other developers who wish to use their systems. As such, it is only meant to document the header files that. Also, it only generates HTML.

Doxygen is a complete source code documentation and browsing system. It documents everything (the internal headers, the external headers and the source code) and is very useful for package maintainers and developers. It also generates good interface documentation and some cool class diagrams. Doxygen generates HTML, XML, LaTex, RTF and other formats.

Here is what I have been told by ccdoc users:

• Ccdoc does a better job of handling certain C++ constructs, specifically namespaces (especially anonymous namespaces) and templates.
  I would be very interested understanding more about this because I use ccdoc to document our local copy of STL so that I can browse it. I have never tried this with doxygen.
• Ccdoc is faster than doxygen which is not suprising since it does less. This makes it suitable for very large systems. I know of one company that uses on a 10M LOC code base. The documentation is generated in about 30 minutes.
• Ccdoc is simpler to use. My own experience is that both tools are pretty easy to use. Doxygen requires a configuration file and ccdoc uses command line switches.
  I think that both approaches work equally well.
• They like the output format better.
  Of course the ones that don't like the output format switch to doxygen and I never hear about it.

It is interesting to note that I did a survey in the summer of 2002 to determine whether I should drop ccdoc in favor of doxygen. I received about 30 responses which was good since the survey was posted to my web page and was not specifically targetted to anyone because I am totally anti-spam. All of the respondents asked me to continue to support ccdoc for the reasons cited above.

Since both tools are free I don't see any reason not to try both of them and use the one that works best for you.

Date: 2003/02/23

It is the result of practicality and philosophy.

From a philosophical perspective, I believe that systems should be self documenting so the help can be found easily.

From a practical standpoint, the easiest thing to do from a documentation perspective is update the help text file while I am working. The upshot of this is that the on-line help is always the last word on the behavior of the program. When all the changes are finished and tested, I then update the users guide and/or the FAQ.

Date: 2003/02/23

Here is one that I recently used for a test case. I have added comments to make it bit more understandable.

@REM =====================================
@REM Ccdoc batch file.
@REM The argument is the output directory.
@REM This batch file is run as follows:
@REM C:> gendoc htdocs
@REM =====================================
if missing%1 == missing goto error

@REM =====================================
@REM Thoroughly clean out the target directory.
@REM =====================================
del /q %1\*.*

@REM =====================================
@REM Phase 1 processing.
@REM =====================================
ccdoc -db %1\ccdoc.db -pkg Utilities Utilities\export\*.h
ccdoc -db %1\ccdoc.db -pkg Library Library\export\*.h

@REM =====================================
@REM Phase 2 processing.
@REM =====================================
ccdoc -db %1\ccdoc.db -index

@REM =====================================
@REM Phase 3 processing.
@REM Note that I used forward slashes
@REM here as a directory separator. I am
@REM not sure whether it matters but this
@REM definitely works.
@REM Also notice that the -html argument
@REM has a trailing directory separator.
@REM This is very important because this
@REM argument specifies a prefix NOT
@REM necessarily a directory. With the
@REM directory separator it definitely
@REM indicates a directory in this case.
@REM =====================================
ccdoc -db %1\ccdoc.db -rptmac1 -html %1/ -rootfile %1/index.html -srcurl ../
goto end

error:
@echo Missing directory name argument.

:end

Date: 2004/09/30

There is no automatic way to log an issue, just send me e-mail describing the issue and I will add it to the list.