$Id: faq.txt,v 1.2 1999/06/14 12:44:25 jdl Exp $

================================================================
CONTENTS

    1.0 What is CcDoc?
    1.1 What is the latest version?
    1.2 How much does it cost?
    1.3 What support options are available?
    1.4 What other documentation packages are available?
    
    2.0 Getting CcDoc
    2.1 Where can I get CcDoc for Windows NT/98?
    2.2 Where can I get CcDoc for Solaris?
    2.3 Where can I get CcDoc for HP?
    2.4 Where can I get CcDoc for Linux?
    2.5 Where can I get CcDoc for AIX?
    2.6 How do I unpack CcDoc binaries under unix?
    2.7 How do I unpack CcDoc source code under unix?
    2.8 How do I unpack CcDoc binaries under Windows?
    2.9 How do I unpack CcDoc source code under Windows?

    3.0 Building CcDoc
    3.1 What tools do you use?
    3.2 What is the directory structure?
    3.3 How do I build CcDoc?
    3.4 How do I backup CcDoc?
    3.5 What revision control system do I use?

    4.0 Running CcDoc
    4.1 What does phase 1a do?
    4.2 What does phase 1b do?
    4.3 What does phase 2 do?
    4.4 What does phase 3 do?
    4.5 What are the CcDoc switches?
    4.6 What environment variables does CcDoc recognize?

    5.0 What is the CTF file?
    5.1 How do I merge CTF files?
    
    6.0 Documentation Tips
    6.1 What is the basic comment syntax?
    6.2 What CcDoc directives are available?
    6.3 How do I tell CcDoc to ignore sections of code?
    6.4 How do I document the root level?
    6.5 How do I document a package?
    6.6 How do I embed references to third party tools like RogueWave?
    6.7 How do I document a class?
    6.8 How do I document a method?
    6.9 How do I document a variable?
    6.10 How do I document an enumerated type?
    
    7.0 Miscellaneous
    7.1 How do I embed hyperlinks to CcDoc generated targets in v0.7 and later?
    7.2 Can I embed my comments in the source file rather than the header file?
    7.3 Does CcDoc support '//' style comments?
    7.4 How can I embed code fragments in my documentation?
    7.5 How do I customize the trailer?

================================================================
1.0 Introduction

    CcDoc tool is a javadoc like tool that automatically
    generates web documentation from C and C++ programs by parsing
    the source file headers (interface definitions). The latest
    versions (v0.7a or later) can also extract documentation from
    from implementation files (.cpp).

    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 capability allows CcDoc to be run over code with a
    different comment style (or no 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 at jlinoff@ix.netcom.com.

1.1 What is the latest version?

    The latest version of CcDoc is v0.7a, released June 1999.

1.2 How much does it 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.

1.3 What support options are available?

    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
 
        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  You support the program at your
                      site using the source code that
                      is provided.

                      You can download the periodic
                      upgrades and bug fixes when you
                      need them.

           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.

1.4 What other documentation packages are available?

    Please look at this web site for list of C++
    documentation systems:

      http://nz.com/webnz/robert/cpp_site.html#Documentation

================================================================
2.0 Getting CcDoc

    CcDoc has been ported to a number of platforms by various
    folks. I will try to keep track of them here.

2.1 Where can I get CcDoc for Windows NT/98?

    You can download it from http://www.joelinoff.com/ccdoc .

2.2 Where can I get CcDoc for Solaris?

    You can download it from http://www.joelinoff.com/ccdoc .

2.3 Where can I get CcDoc for HP?

    Although I have built CcDoc under HP, the executable
    is so large, that I can put it on my web site (>8Mb).

    I recommend that you download the source from
    http://www.joelinoff.com/ccdoc and compile it
    locally.

2.4 Where can I get CcDoc for Linux?

    A number of folks have ported CcDoc to Linux and I
    have incorporated their suggestions. I am told that
    it compiles correctly with no changes.

    I recommend that you download the source from
    http://www.joelinoff.com/ccdoc and compile it
    locally.

    One of my hopes is that I will get enough money from
    the shareware to get a linux system so that I can 
    build the linux version myself.

2.5 Where can I get CcDoc for AIX?

    A number of folks have ported CcDoc to AIX and I
    have incorporated their suggestions. I am told that
    it compiles correctly with no changes.

    I recommend that you download the source from
    http://www.joelinoff.com/ccdoc and compile it
    locally.

2.6 How do I unpack CcDoc binaries under unix?

    Download ccdoc_v07a_bin_taz.exe to your local system.

        % mkdir ccdoc_dev
        % cd ccdoc_dev
        % # Download from http://www.joelinoff.com/ccdoc
        % mv ccdoc_v07a_bin_taz.exe ccdoc_v07a.taz
        % gunzip ccdoc_v07a.taz
        % tar xvf 

2.7 How do I unpack CcDoc source code under unix?

    Download ccdoc_v07a_src_taz.exe to your local system.

        % mkdir ccdoc_dev
        % cd ccdoc_dev
        % # Download from http://www.joelinoff.com/ccdoc
        % mv ccdoc_v07a_src_taz.exe ccdoc_v07a.taz
        % gunzip ccdoc_v07a.taz
        % tar xvf 
        % perl tools/ccdoc_pc2unix.pl perl
        % perl tools/ccdoc_bld.pl

    In some cases (for example, HP) you might have to edit the
    tools/ccdoc_pc2unix.pl script to manually remove the ^M
    characters.

2.8 How do I unpack CcDoc binaries under Windows?

    Make sure that you have winzip on your system.
    You can download it from http://www.winzip.com.

    Download ccdoc_v07a_bin_taz.exe to your local system.

        % # Download from http://www.joelinoff.com/ccdoc to C:\TEMP
        % rename ccdoc_v07a_bin_taz.exe ccdoc_v07a.taz
        % call winzip ccdoc_v07a.taz

2.9 How do I unpack CcDoc source code under Windows?

    Make sure that you have rktools (or any other tool
    set that provides tar, gzip, gunzip, ls, mkdir, cd,
    grep, etc.), tcsh and perl.

    You can use winzip to unzip the archive but I recommend
    using the unix type tools because that is how the
    development environment is set up.

    Download ccdoc_v07a_src_taz.exe to your local system.

        % mkdir ccdoc_dev
        % cd ccdoc_dev
        % # Download from http://www.joelinoff.com/ccdoc
        % mv ccdoc_v07a_bin_taz.exe ccdoc_v07a.taz
        % gunzip ccdoc_v07a.taz
        % tar xvf 
        % perl tools/ccdoc_bld.pl

================================================================
3.0 Building CcDoc

    I develop and build CcDoc on three systems: a Windows 98/NT,
    HP-UX B.10.20 and Solaris 5.6.

3.1 What tools do you use?

    I use tcsh as my command shell in all environments.

    I use standard unix tools (rktools on the PC) for everything
    except the compiler and make system.

    I use the Solaris CC 4.2 compiler, the /opt/CC/bin/CC compiler
    under HP (it has no version switch!) and MS VC++ 5.0 or 6.0.

    I use standard unix make on all platforms other than windows,
    I use NMAKE under Windows.

    I use emacs 20.3 or later as my editor in all environments.

    I use scripts written in perl 5.003 (or later) on all machines for
    a common build interface. Those scripts are stored in the tools
    subdirectory.

3.2 What is the directory structure?

    The CcDoc directory structure is:

       ccdoc_dev +--> ccdoc -+---> doc      // documentation
                 |           |
                 |           +---> images   // GIF images
                 |           |
                 |           +---> src      // source files
                 |           |
                 |           +---> test     // regression tests
                 |           
                 +--> libjdl +---> doc      // documentation
                 |           |
                 |           +---> src      // source files
                 |           |
                 |           +---> test     // regression tests
                 +--> tools                 // porting tools

3.3 How do I build CcDoc?

    For a unix platform you must strip the ^M characters off
    of most things. This can be done by first manually removing
    the ^M characters from the tools/ccdoc_pc2unix.pl tool (this step
    is not necessary under Solaris or Windows) and then running
    this tool as follows:

    % cd ccdoc_dev
    % perl tools/ccdoc_pc2unix.pl perl

    After that do this:

    % cd ccdoc_dev
    % perl tools/ccdoc_bld.pl

    I also created the alias: "alias b perl mk.pl" for building
    individual pieces of the system.

    To build only the debug version of CcDoc I would do the
    following:

        % cd ccdoc_dev/ccdoc/src
        % b dbg

    The standard target for building debug versions is "dbg",
    the standard target for building opt versions is "opt".
    The standard target for testing is "test".

    The makefile for each platform is generated automatically
    and uses the local suffix.mk for customization.


3.4 How do I backup CcDoc?

    A snapshot backup of CcDoc is created as follows:

        % cd ccdoc_dev
        % tools/ccdoc_snp.sh

    You must have a valid version of tar and gzip in your
    path for this to work correctly.

3.5 What revision control system do I use?

    I use RCS 5.x or later under Windows and Unix.

================================================================
4.0 Running CcDoc, the different phases.

    CcDoc operates in 3 phases:

        Phase 1 - Parse the individual source files.
        Phase 2 - Create the cross reference for all items.
        Phase 3 - Generate C++.

    Phase 1 is further broken down into two parts:

        Phase 1a - Parse the interface files (.h).
        Phase 1b - Parse the implementation files (.cpp).

    Phase 1b is new in v0.7a. This phase allows programmers
    to add comments to the implementation files rather than
    the interface files.

    The following sections describe each of these phases
    in greater detail.

4.1 What does phase 1a do?

    Phase 1a 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.

    Shown below is a simple example of phase 1a processing:

        % rm -f x.ctf
        % ccdoc -ctf x.ctf -pkg utils utils/*.h
        % ccdoc -ctf x.ctf -pkg code  code/*.h

4.2 What does phase 1b do?

    Phase 1b processing is an extension of phase 1a process that
    parses implementation files. The implementation files must be
    processed after the interface files so that method scope can
    be determined.

    Shown below is a simple example of phase 1b processing:

        % ccdoc -ctf x.ctf -pkg utils utils/*.cpp
        % ccdoc -ctf x.ctf -pkg code  code/*.cpp

4.3 What does phase 2 do?

    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.

    Shown below is a simple example of phase 2 processing:

        % ccdoc -ctf x.ctf -index

4.4 What does phase 3 do?

    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.

    Shown below is a simple example of phase 3 processing:

        % ccdoc -ctf x.ctf \
                -v \
                -html webdocs/ \
                -srcurl http://where.the.source.is/src/ \
                -imgurl http://www.joelinoff.com/ccdoc/images/ \
                -trailer suffix.html \
                -header prefix.html

4.5 What are the CcDoc switches?

    Switches use by all phases.

    Switch                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 (these work for both subphases)

    Switch                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

    Switch                Description
    ====================  ==============================================
    -index                Index the contents of the parse tree.


    Phase 3 Switches

    Switch                Description
    ====================  ==============================================
    -bg <color>           The background color. The default is white
                          (#FFFFFF).

    -header <file>        The HTML used for the customized prefix.

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

4.6 What environment variables does CcDoc recognize?

    Variable              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_PHASE1B_OFF     Turn off phase 1b processing. This will make CcDoc
                          run slightly faster.

    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. 

================================================================
5.0 What is the CTF file?

    The CTF file for CcDoc Token Format file stores the tokenized
    information about the C++/C entities that CcDoc has parsed.

    The CTF file is composed of four sections:

        1. the version section ('v' record)
        2. the string section ('s' record)
        3. the node information section ('n' and 'd' records)
        4. the cross reference section ('x' record)

    These sections are always produced in the same order.

    General Notes:

        Comments:

            Comments are delimited by a hash mark (#) and the end of
            the line. If the hash mark is within a string, it does
            not begin a comment. If the hash mark is part of a string
            record it is also not a comment.

            A sample comment is shown below:

                # This is a CTF comment

        Record Format:

            All CTF records has the same basic format. They start
            at the beginning of line with a single character
            identifier. The record fields are separated by colons.

            The record types are:

                'd' - node data record
                'n' - node record
                's' - string record
                'v' - version record
                'x' - cross reference record

            There is one record per line.

        Debug Mode:

            In debug mode the string value is printed out as well as
            its contents. These debug strings always have the
            following syntax and appear on the same line as
            the record that contains the referenced string.
        
                " %x:%s"
                 ^^  ^
                 ||  +--- string value
                 |+------ string length
                 +------- debug marker (space)

            Debug mode is not efficient because it duplicates
            the string values.

    Version Section:

        The first entry in a CTF file is the version record ('v').

        The syntax of the 'v' record is shown below:

            "v:%s:%s:%s\n"
             ^ ^  ^  ^
             | |  |  +------- the state of the processing
             | |  +---------- the minor version number (7a)
             | +------------- the major version number (0)
             +--------------- the record identifier

    String Section:

        To save space, strings are stored in an index at the head
        of the file.

        Each entry is called an 's' record (for string
        record) and has the following syntax:

            "s:$%x:%x:%s\n"
             ^ ^   ^  ^
             | |   |  +-------- the string data
             | |   +----------- the string length (hex)
             | +--------------- the string id form: $<hex num>
             +----------------- the record identifier
    
        The first 128 string records are implied, they are the
        first 128 ASCII characters. Thus, when the value $20 is
        encountered as a string reference, the system knows that
        this is a space (' ' == hex 20).

    Node Section:

        Nodes are hierarchical entities that describe the
        C++ entity relationships.
    
        Each node record contains the following information.
    
            "n:%s:%s:r%x:%x:%x:%x:%x:$%x"
             ^ ^  ^  ^   ^  ^  ^  ^  ^
             | |  |  |   |  |  |  |  +-- name id
             | |  |  |   |  |  |  +----- num d records
             | |  |  |   |  |  +-------- lineno
             | |  |  |   |  +----------- offset from parent
             | |  |  |   +-------------- level
             | |  |  +------------------ xref id
             | |  +--------------------- scope name (public, private, ...)
             | +------------------------ type name
             +-------------------------- record type indicator
    
        In addition, it contains a list of data ('d') nodes whose
        format is:
    
            "d:%c:$%c"
             ^ ^  ^
             | |  +----- string id
             | +-------- type: i-id, r-reserved, k-keyword, ?-unknown
             +---------- record type
    
        The 'd' records are the list of strings associated with
        the node that comprise the original C++ construct.

        The scope names are three character strings. The available
        scope names are:

            ID   Description
            ===  ===============
            ???  unknown scope
            gbl  global scope
            loc  local scope
            pri  private scope
            pro  protected scope
            pub  public scope

        The type names are three character strings. The available
        type names are:
    
            ID   Description         ID   Description
            ===  =================   ===  =================
            asm  asm                 nms  namespace
            cls  class               nma  namespace alias
            clc  constructor         prg  pragma
            cld  destructor          pri  private
            cfw  class forward ref   pro  protected
            cmb  brief comment       pub  public
            cmf  full comment        scf  scoped function
            cmd  @<directive>        stf  scoped template function
            cmp  @pkg                str  struct
            cmx  @pkgdoc             sfw  struct forward ref
            enm  enum                tmc  template class
            fil  file                tfw  template forward ref
            frc  friend class        tmf  template function
            frf  friend function     typ  typedef
            fct  function            uni  union
            inc  include             use  using 
            mac  macro               var  variable
            mai  macroinst           ???  ?Unknown?

    The Cross Reference Section:
    
        This section keeps a cross reference all node records
        with the same name.

        The record format is:

            "x:%x[:r%x]+:$%x"
             ^ ^   ^     ^
             | |   |     +---- string id
             | |   +---------- 1 or more reference sub records
             | +-------------- number of reference sub records
             +---------------- record id

5.1 How do I merge CTF files?

    CTF files can be merged with the ctf_merge.pl script
    provided in release v0.7a. The example below shows
    how to run this script.

        % perl ccdoc_merge.pl -i A.ctf -i B.ctf -o C.ctf
        % ccdoc -index -ctf C.ctf

    You can have any number of input files (-i) but only
    one output file (-o).

================================================================
6.0 Documentation Tips

    This section presents documentation tips.

6.1 What is the basic 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.

6.2 What CcDoc directives are available?

    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 ignoring sections
                                 of code. 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 documentation.

                                 You can use these directives to tell CcDoc to 
                                 ignore them as follows:

                                     #ifndef _this_include_file
                                     /**@#-*/
                                     #define _this_include_file
                                     /**@#-*/
                                     .
                                     .
                                     #endif

                                 Another way to do this is to use the __ccdoc_
                                 macro as follows:

                                     #ifndef _this_include_file
                                     #ifndef __ccdoc__
                                     #define _this_include_file
                                     #endif
                                     .
                                     .
                                     #endif

                                 The latter method is preferred.

    @@                           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: faq.txt,v 1.2 1999/06/14 12:44:25 jdl Exp $
                                      */

    @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:$. 

6.3 How do I tell CcDoc to ignore sections of code?

    There are two ways to tell CcDoc to ignore sections of
    code. Both are shown in the example below:

    #ifndef __ccdoc__
    // Ignore class A
    class A {
    };
    #endif

    /**@#-*/
    // Ignore class B
    class B {
    };
    /**@#+*/

    The preferred method is to use the predefined 
    macro __ccdoc__. The second method is more
    arcane but is maintained for backward compatibility.

6.4 How do I document the root level?

    The easiest way to document the root level of
    a system is to create a file called "root.pkg"
    and insert your documentation.

    The example below shows what a root.pkg file
    might look like:

        // Top level documentation.
        /**@pkg [NULL]*/

        // TOP
        /**
         * My stuff root level documentation.
         * @author FooBar
         * @version $Id: faq.txt,v 1.2 1999/06/14 12:44:25 jdl Exp $
         * @pkgdoc [ROOT]
         */

    This file is then run through ccdoc phase 1 processing
    as a normal file.

6.5 How do I document a package?

    In general, to document a package you use the @pkgdoc
    directive. I generally create a single file called "root.pkg"
    that contains the documentation for all packages.

    The example below shows how the ROOT level is redefined
    (same as 6.1) and package documentation for an intermediate
    level is also added.

        // Package documentation.
        /**@pkg [NULL]*/

        // TOP
        /**
         * My stuff root level documentation.
         * @author FooBar
         * @version $Id: faq.txt,v 1.2 1999/06/14 12:44:25 jdl Exp $
         * @pkgdoc [ROOT]
         */

        // TOP.intermediate
        /**
         * My stuff intermediate level documentation.
         * @author FooBar
         * @version $Id: faq.txt,v 1.2 1999/06/14 12:44:25 jdl Exp $
         * @pkgdoc intermediate
         */

6.6 How do I embed references to third party tools like RogueWave?

    The example below shows how to embed documentation for
    third party tools like Rogue Wave tools.h++.

        // Package documentation.
        /**@pkg [NULL]*/

        // TOP
        /**
         * My stuff root level documentation.
         * @author FooBar
         * @version $Id: faq.txt,v 1.2 1999/06/14 12:44:25 jdl Exp $
         * @pkgdoc [ROOT]
         */

        // TOP.intermediate
        /**
         * My stuff intermediate level documentation.
         * @author FooBar
         * @version $Id: faq.txt,v 1.2 1999/06/14 12:44:25 jdl Exp $
         * @pkgdoc intermediate
         */

        // TOP.RogueWave
        /**@Intermediate.RogueWave http://internal/rw/toosug/ug.htm */

6.7 How do I document a class?

    The basic comment structure looks like this:

        /**
         * <brief>
         *
         * <full>
         * <directive>
         * .
         * .
         * <directive>
         */
    
    An example comment for a class might look like this:

        /**
         * This is the block interface class.             | Brief
         *
         * The block interface class provides the         | Full
         * the interface that is used by clients when     | Full
         * specializing their classes.                    | Full
         *                                                | Full
         * A client might specialize a class like this:   | Full
         *<pre>                                           | Full
         *@@    class MyBlock : public Block {            | Full
         *@@      .                                       | Full
         *@@      .                                       | Full
         *@@    };                                        | Full
         *</pre>                                          | Full
         *@author Joe Linoff                              | Directives
         *@version $Id: faq.txt,v 1.2 1999/06/14 12:44:25 jdl Exp $                                  | Directives
         *@see Bridge                                     | Directives
         *@see BlockData                                  | Directives
         */
        class Block {
        };

    The directives that are most often used for a class are @author,
    @version and @see.

    The *@@ prefix is used to tell CcDoc to substitute the
    angle brackets correctly. Always use this for code
    examples. If you don't the HTML parser will get confused
    by things like:

       for(int i=0;i<10;i++) {

    It will think that <10 is the start of an HTML command.
    When you specify the @@ operator is converts the < to
    a &lt; so that the HTML comes out properly.

    The HTML commands <pre> and </pre> are used to delimit
    code.

6.8 How do I document a method?

    Methods are documented in a similar fashion as shown below:

        class A {
        public:
          /**
           * Get the type.
           *
           * The type of this class is used to determine
           * whether you can do useful stuff, blah, blah.
           * Complete information about the types available
           * are described in
           * @$ #SetType
           * .
           * The example below shows how a client might
           * use this method.
           *<pre>
           *@@  A::TYPE t = obj->GetType();
           *@@  switch(t) {
           *@@  case A::FOO: ... break;
           *@@  default: ... break;
           *@@  }
           *</pre>
           * @param detailed If true, return the detailed type.
           * @returns The object type.
           * @see #SetType
           */
          TYPE GetType(bool detailed=false) const;
        };

    The most common directives used in method documentation
    are @param, @returns and @see.

    The @$ operator tells CcDoc to insert an anchor reference
    to the specified class or method.

    Some folks prefer to put the method documentation in the
    source file. The example below shows how this is done:

        a.h:
            class A {
            public:
              TYPE GetType() const;
            };

        a.cpp:
            #include "a.h"

            /**
             * Get the type.
             *
             * The type of this class is used to determine
             * whether you can do useful stuff, blah, blah.
             * Complete information about the types available
             * are described in
             * @$ #SetType
             * @returns The object type.
             * @see #SetType
             */
            A::TYPE A::GetType() const {...}

6.9 How do I document a variable?

    Variables can be effectively documented with only the @see
    and @$ directives. As shown in the example below:

        class Globals {
        public:
          /**
           * This variable defines the singleton for the
           * the entire system.
           *@see CBase
           */
          extern CBase* s_Singleton;
        };

6.10 How do I document an enumerated type?

    You document enumerated types in fashion very similar
    to variables. You cannot document each type separately
    so describe all of them in variable comment.

    The example below shows how this is done.

        /**
         * These are the global types recognized by the
         * system.
         *
         * The types are:
         *<pre>
         *    Type      Description
         *    ======    ====================================
         *    INT       32 bit signed integer.
         *    STRING    NULL terminated unsigned char array.
         *    SENTINEL  The end of the list (used for loops).
         *</pre>
         */
        enum GLOBAL_TYPES {
          INT,
          STRING,
          SENTINEL
        };

================================================================
7.0 Miscellaneous

    This section presents answers to specific questions.

7.1 How do I embed hyperlinks to CcDoc generated targets?

    Use the @$ directive that became available in v0.7a.
 
        /**
          * Brief description, take a look at
          * @$ Class::Method
          * for more information.
          */

7.2 Can I embed my comments in the source file rather than the header file?

    In CcDoc v0.7a, the program will allow you
    to define comments in your source file. The
    brief example below shows how this is done:
 
        test.h:
            class A {
            public:
              void DoStuff();
            };
 
        test.cpp:
            /**
             * CcDoc comment here.
             */
            void A::DoStuff() {
            }
 
        command line:
            % rm test.ctf
            % ccdoc -ctf test.ctf test.h
            % ccdoc -ctf test.ctf test.cpp
            % ccdoc -ctf test.ctf -index
            % ccdoc -ctf test.ctf -html ...
    Note that using this feature causes CcDoc to run
    more slowly because it has to process many more
    files.
 
7.3 Does CcDoc support '//' style comments?

    Yes. 
 
    The problem here is that CcDoc expects a multi-line
    comment form and many code generation tools, such as
    Rose, generate comments in the single line form.
 
    In v0.7a, CcDoc accepts comments of the form:
 
        ///**
        // * Brief description.
        // *
        // * Full description. 
        // * @directives.
 
    to allow easy integration with code generation tools like
    the Rose tool.

7.4 How can I embed code fragments in my documentation?

    You can embed code fragments in your documentation by
    using a combination of the HTML <pre> and </pre> tags
    and the CcDoc *@@ directive. The example below shows how
    this is done.

        /**
         * Brief comment.
         *
         * Full comment with an embedded code
         * fragment:
         *<pre>
         *@@ int main(int argc,char** argv) {
         *@@   {for(int i=0;i<argc;i++) {
         *@@     print("argv[%d] = '%s'\n",i,argv[i]);
         *@@   }}
         *@@   return 0;
         *@@ }
         *</pre>
         */

    If you do not use the @@ directive, the < in the for loop
    will confuse most HTML parsers, they will try to find the
    <argc tag.

7.5 How do I customize the trailer?

    Create a trailer file and reference it using the
    -trailer switch in phase 3. The example below
    shows how to create a trailer file called trailer.html
    for a product called Foo.

        % cat trailer.html
        <!-- Custom trailer for Foo v1.0 -->
        <center>
        <font size="-1">
        <p>
        This documentation was generated automatically by the 
        CcDoc v0.7a for Foo v1.0.
        <br>
        Click <a href=\"mailto:Owner\">here</a>
         to submit a bug report or feature request to Owner.
        </font>
        </center>
        % ccdoc -ctf foo.ctf -trailer trailer.html ...
