ccdoc v08r41 2004/09/29 bin_dbg_msvc_MSWin32-x86-multi-thread-4.0
ccdoc help 2004/09/29
Copyright (C) 1998-2004 by Joe Linoff.

For more information see http://ccdoc.sourceforge.net or
http://www.joelinoff.com/ccdoc.

  Table of Contents

  Introduction ......................................  1
  Phase Independent Switches ........................  2
  Parse Phase .......................................  3
  Index Phase .......................................  4
  Output Phase ......................................  5
  Running the Program ...............................  6
  Comment Directives ................................  7
  Comment Format ....................................  8
  Package Help ......................................  9

1 Introduction

  This program analyzes C++ declarations and produces HTML
  documentation.

  It has three basic operating phases: Parse, Index and Output. Each
  phase is described in more detail below.

    Phase   Description
    ======  ==========================================
    Parse   Parse C++ declarations and ccdoc comments.
    Index   Generate cross references.
    Output  Generate HTML output.

  Phases are defined by the switches that are used on the command
  line. Multiple phases can be specified in a single run. The phases
  are described in the following sections. Each section describes the
  phase specific switches and presents some usage examples.

  After the phases have been discussed there is a section on flow
  which describes different usage models and, following that, there is
  a summary of the ccdoc comment directives.

2 Phase Independent Switches

  This section presents the switches that can be used in any phase or,
  as is the case with -h, no phase.

  Switch        Description
  ============  ======================================================
  -args         Dump the command line arguments. This is enabled
                automatically in verbose (-v) mode.

  -cid          Deprecated. Same as -verbose.

  -ctf <file>   Deprecated. Same as -db.

  -db <file>    The name of the ccdoc database.

  -h,-help      Displays the extensive on-line help and exits.
                The on-line covers the different program phases, the
                comment directives and the program switches.

  -log <file>   All information output by the program is also sent
                to the specified log file. Multiple log files can be
                specified. By default all output is sent to cout.

  -nocout       Turn off output to cout. This is used to test the
                help output without displaying anything to the
                console.

  -putenv <env> Set an environment variable from the command line.
                This is useful for setting up regression tests in
                scripts on various platforms.

  -[no]v        Turn verbose mode on or off. The default is off.

  -version      Report the program version. The version contains the
                program name, the version, the revision, the release
                date and the compilation id. Here is an example of
                what -version reports:
                  % ccdoc -version
                  ccdoc v08r41 2004/09/29 bin_opt_msvc_MSWin32-multi-thread-4.0

  -[no]vf       Turn db verbose format mode on or off. The default is
                on because it speeds up the writing significantly and
                is only slightly larger. This switch enables verbose
                mode in the database file to make things easier to
                read for debugging.

  -[no]warn     Turn warnings on or off. The default is on.
  ============  ======================================================

  Here is an example that shows how to output this help information to
  a log file:

    % ccdoc -log help.log -h

3 Parse Phase

  During the parse phase C++ files are parsed to find declarations and
  ccdoc comments. These entities are tokenized and stored into the
  database specified by the -db switch. The parse phase is specified
  by the -pkg switch or the presence of source files on the command
  line.

  When new files are parsed, the indexing information from previous
  runs is lost.

  Switch              Description
  ==================  ==================================================
  -[no]cdsm           Turn on or off the creation of default special
                      members for classes. Specifically this tells ccdoc
                      to create (or not create) entries for default
                      constructors, copy constructors, destructors and
                      copy operators if they were not explicitly defined
                      in the class. The default is -cdsm.

  -db <file>          The name of the ccdoc database.

  -D<name>[=<value>]  Define a macro and, optionally, define its value.

  -[no]doxygen        Enable limited doxygen compatibility mode.
                      The default is -doxygen.
                      This switch specifies that @file
                      blocks are ignored.

                      Some other doxygen compatible syntax is already
                      supported whether this switch is specified or
                      not, namely: the @endlink directive, the single
                      line suffix comment forms (//!< and ///<) and
                      the multiple line suffix comment forms (/*!< and
                      /**<).

                      This allows users more flexibility in converting
                      between doxygen and ccdoc.

  -files <list>       Designates a file that contains the list of files
                      to parse.

  -[no]jdsds          Enable javadoc short description syntax. This
                      causes ccdoc to conform to the javadoc
                      specification for processing short descriptions.

                      This is the new default behavior as of r24.

                      A javadoc short description is terminated by a
                      period followed by a space, tab, newline or tag
                      (directive).

                      If -nojdsds is specified, the old-style ccdoc
                      short description handling is enabled. That is,
                      short descriptions are terminated by a blank
                      line.

  -pkg <name>         Define the package name for the entities in the
                      source files. If no package is specified a
                      default name is used or the @pkg <name>
                      directive in the ccdoc comment is used. Children
                      (like class methods) inherit the package from
                      their parent.

  -[no]tcms           Turn on or off the processing of template class
                      methods that are defined outside of the class
                      declaration.

  -U<name>            Undefine a macro.
  ==================  ==================================================

  Here is an example that shows how multiple header files are parsed
  from different source directories into a common database.

    ccdoc -db /tmp/ccdoc.db -pkg Utilities project/utils/export/*.h
    ccdoc -db /tmp/ccdoc.db -pkg Parser project/parser/export/*.h

4 Index Phase

  During the index phase ccdoc analyzes the database to find
  associations between related entities. For example, if class Child
  derives from class Parent, this phase will find Parent and link it
  to the Child record so that a link can be generated during the
  output phase. The index phase is specified by the -index switch.

  If the index phase is not run, the output will contain no links.


  Switch          Description
  ==============  ===============================
  -db <file>      The name of the ccdoc database.

  -index          Generate the indices.
  ==============  ===============================

  Here is a use-case that shows how generate an index for a database.

    ccdoc -db /tmp/ccdoc.db -index

5 Output Phase

  During the output phase, ccdoc generates HTML from the database.
  This phase is optional. A user could develop their db reader and
  output any another format (like XML). The output phase is specified
  by the -htm or the -html switch.

  After this phase is run, a top level file called
  ccdoc.<root>.pkg.html will exist in the specified html path.

  Switch              Description
  ==================  ======================================================
  -bg <color>         The background color. The default is the default for
                      the browser.

  -db <file>          The name of the ccdoc database.

  -dospaths           The file paths contain backslashes that need to be
                      converted to forwards slashes for HTML.

  -htm <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.
                      Always use a forward slash to separate directories,
                      even when you are running under a DOS window, because
                      the HTTP path hierarchy separator is a forward slash.

  -fg <color>         Same as -fgtext.

  -fgtext <color>     The foreground text color. The default is the default
                      for the browser.

  -fglink <color>     The foreground link color. The default is the default
                      for the browser.

  -fgvlink <color>    The foreground vlink color. The default is the default
                      for the browser. These are used links.

  -header <file>      The HTML used for the customized header just after
                      the <body> stmt. This is where clients insert their own
                      custom information on each page. See the -meta command
                      for information on how to insert meta variables in
                      the <head> section.

  -imageurl <URL>, 
  -imgurl <URL>       The URL that describes of the GIF images. This
                      version of ccdoc does not use images so this switch
                      has no effect.

  -[no]macros         Deprecated. Same as -[no]rptmac.

  -maxpathlen <num>   Maximum file path size. The default is 128. When the
                      file path size exceeds the limit, the file name
                      is truncated and a checksum is added to guarantee
                      that the file name is unique. If maxpathlen is set
                      to zero, no limit checking is performed.

  -meta <file>        The HTML used for the customized header just after
                      the <head> stmt. This is where clients insert their own
                      custom information for meta variables on each page.
                      If -meta is specified, ccdoc will not generate the
                      the http-equiv meta variable for HTML 4.01 compliance
                      and it will ignore the -rptctcs.

  -[no]private        Deprecated. Same as -[no]rptpri.

  -[no]protected      Deprecated. Same as -[no]rptpro.

  -[no]public         Deprecated. Same as -[no]rptpub.

  -root <name>        Change the name of the root package from 'root' to
                      something else.

  -rootfile <name>    Change the top level output file name from
                      <prefix>ccdoc.root.pkg.html to whatever the user
                      wants. This can be used to create the ccdoc.index.html
                      file by specifying: -rootfile ccdoc.index.html.
                      This switch allows you to completely specify the
                      path. The -html prefix is ignored.

  -rootpurl <URL>
  -rooturl <URL>      The hyperlink for the parent of the root package.
                      Setting this allows the generated HTML to seamlessly
                      integrate to a higher level document by providing a back 
                      link to the users parent page.

  -[no]rptcfuns       Report comments for undocumented namespaces. When
                      -rptcfuns is specified, all related namespaces
                      comments are reported. This includes namespaces
                      that do not contain ccdoc comments which can be
                      somewhat busy. When -norptcfuns is specified, only
                      related namespaces with ccdoc comments are reported.
                      The only exception is when none of the namespaces
                      have ccdoc comments. In that case, only the first
                      undocumented namespace is reported (for backward
                      compatibility). The default is -norptcfuns.

  -[no]rptcsd         Report class summary details. When -rptcsd is
                      specified, the class summary page reports type, access
                      and short description information. When -norptcsd
                      is specified the class summary page only reports the
                      names. The default is -rptcsd.

  -[no]rptcsi <num>   The class summary indent switch. Define the indent 
                      level of each entry in the class summary report and
                      the contents column. The default indent level is 4.

  -rptctcs <string>   Allow the user to specify the Content-Type char set.
                      This allows international languages to be supported.
                      The default char set is "iso-8859-1".
                      This switch is ignored if the -meta switch is specified.

  -rptdefa <string>   Set the default string for the author field in
                      top level entities. The default is "unascribed".

  -rptdefasd <string> Set the default string for the automatically generated
                      short description field in top level entities. The
                      default is "automatically generated".

  -rptdefsd <string>  Set the default string for the short description
                      field in top level entities. The default is
                      "undocumented".

  -rptdefv <string>   Set the default string for the version field in
                      top level entities. The default is "unknown".

  -[no]rptdpa         If the package author is not specified, report the
                      author as unascribed. The default is -norptdpa which
                      tells ccdoc to ignore authors on packages unless they
                      are explicitly specified.

  -[no]rptdpd         If the package description is not specified, report the
                      description as unknown. The default is -norptdpd which
                      tells ccdoc to ignore descriptions on packages unless
                      they are explicitly specified.

  -[no]rptdpv         If the package version is not specified, report the
                      version as unknown. The default is -norptdpv which
                      tells ccdoc to ignore version on packages unless they
                      are explicitly specified.

  -[no]rptfwcf        The fixed width code font switch. Use a fixed width 
                      font when reporting code fragments. The default is
                      -norptfwcf.

  -[no]rpthpc         Report package contents hierarchically like the
                      the class summary page. The default is -rpthpc.

  -[no]rptim          Report all inherited methods as though they were
                      defined locally. The default is -rptim.

  -[no]rptmac         Report macros. Default is -norptmac because there can be
                      large numbers of guards in header files. If a system is
                      designed with ccdoc in mind, the header guards can be
                      surrounded by ccdoc guards (#ifndef __ccdoc__) which
                      would make this data more useful.

  -[no]rptmac1        Report macros heuristically. This means that ccdoc
                      attempts to filter out header guards and windows
                      DLLIMPORT/DLLEXPORT macros by filtering out macro
                      names with the prefixes: dll_, DLL_, include_, INCLUDE_,
                      included_, INCLUDED_ and the suffixes: dll, _DLL,
                      _h, _H, _hh, _HH, _include, _INCLUDE, _included,
                      _INCLUDED, _included_, _INCLUDED_.

                      The default is -norptmac1.
                      When this switch is enabled, it also enables -rptmac.
                      This is a better choice than -rptmac.

  -rptmlci <num>      Maximum length of the content ids. This switch is
                      used to avoid strange looking tables of content
                      when the id is very long. 

                      When the string exceeds this length, only the
                      first <num> characters are printed followed by
                      .. to indicate truncation.

                      The default length is 32. A value of zero means
                      don't impose the limit. If no inherited from column
                      exists, the value of the -rptmlcifi is added to make
                      this field bigger.

  -rptmlcifi <num>    Maximum length of the contents "inherited from"
                      column id. This switch is used to avoid strange
                      looking tables of content when the parent id is
                      very long.

                      When the string exceeds this length, only the
                      first <num> characters are printed followed by
                      .. to indicate truncation.

                      The default length is 32. A value of zero means
                      don't impose the limit.

  -[no]rptpri         Report private items. The default is -norptpri.

  -[no]rptpro         Report protected items. The default is -norptpro.

  -[no]rptpub         Report public items. The default is -rptpub.

  -[no]rptsci         Report the class information in sorted order. The
                      default is -rptsci. If -norptsci is specified
                      the class contents and details are not sorted.

  -[no]rptsrc         Report the source information for each entity
                      in the table of contents. This causes an additional
                      column to be added to the table. The default is
                      -norptsrc because this information is already
                      reported for each entity in its description. It
                      exists to provide debugging support for when no
                      description is generated.

  -[no]rpttyp         Report typedefs. Default is -rpttyp.

  -[no]rptun          Report unions. Default is -rptun.

  -sourceurl <URL>,
  -srcurl <URL>       The URL where the source files can be found. If this
                      is specified, hyperlinks are created for Source entries.

  -trailer <file>     The HTML used for the customized trailer.

  -[no]typedefs       Deprecated. Same as -[no]rpttyp.

  -[no]unions         Deprecated. Same as -[no]rptun.
  ==================  ======================================================

  Here is a use case that shows how to generate HTML:

    ccdoc -db ccdoc.db -html webdocs/ -imgurl images/ \ -trailer
    custom_trailer.html \ -root MyProject -rooturl myproj.htm

6 Running the Program

  This section presents some example flows to help you understand how
  to use the program more effectively.

  6.1 Simple Flow

  This is the simplest flow. You run all three phases at the same time.

    % ## UNIX:
    % ccdoc \
        -db webdocs/ccdoc.db \
        -pkg simple \
        *.h \
        -index \
        -rootfile webdocs/index.html \
        -html webdocs/

    > REM DOS
    > ccdoc -db webdocs/ccdoc.db -pkg simple *.h -index -rootfile webdocs/index.html -html webdocs/

  Note that it forces the top level html file to be named index.html which
  is convenient for most browsers.

  6.2 Typical Flow

  This is the typical for a usage for a system with multiple packages.
  Each phase is run separately.

    % ### Phase 1a - Parse
    % ccdoc -db typical.db -pkg typical.utils work/utils/src/*.h
    % # Don't report missing default constructors.
    % ccdoc -db typical.db -pkg -nocdsm typical.liba work/liba/src/*.h
    % # Define a macro that is used for my documentation.
    % ccdoc -db typical.db -pkg \
        -DMY_CCDOC_EXTERNAL typical.libb \
        work/libb/src/*.h

    % ### Phase 1b - Parse root level documentation
    % ccdoc -db typical.db -pkg typical typical.txt

    % ### Phase 2 - Index
    % ccdoc -db typical.db -index

    % ### Phase 3 - Output
    %ccdoc \
       -db typical.db \
       -html webdocs/ \
       -rootfile webdocs/index.html \
       -srcurl work/ \
       -trailer custom.htm

7 Comment Directives

  This section presents a brief overview of the ccdoc comment syntax.

  The directives are summarized in the table below.

    Id  Directive      Quick Summary
    ==  =============  =====================================================
     1 /** .. */       Encloses a javadoc style ccdoc comment.
     2 /**< .. */      Encloses a doxygen style suffix ccdoc comment.
     3 /*!< .. */      Encloses a doxygen style suffix ccdoc comment.
     4 //@{ .. //@}    Encloses a ccdoc comment for C++ style line comments.
     5 //@-            Single line suffix C++ style comment form.
     6 ///<            Same as //@- (doxygen compatible).
     7 //!<            Same as //@- (doxygen compatible).
     8 /**@#-*/        Turn off ccdoc token parsing.
     9 /**@#+*/        Turn on ccdoc token parsing.
    10 /**@#=<ch>*/    Insert <ch> into the input stream.
    11 {@link...}      The in-line link specification.
    12 @@              Translate HTML special characters for code fragments.
    13 @$              Same @link.
    14 @author         Specify an author.
    15 @deprecated     Describes the alternatives to use.
    16 @exception      Deprecated, same as @throws.
    17 @link,@endlink  Generate a hyperlink to a ccdoc entity.
    18 @param          Document a function or class method parameter.
    19 @pkg            Specifies the name of a package.
    20 @pkgdoc         This comment documents a specific package.
    21 @pkgdoctid      Redefine the output title id for a pkgdoc.
    22 @return         Deprecated, same as @returns.
    23 @returns        Documents the return value from a method or function.
    24 @see            Add a hyperlink entry to the See section.
    25 @since          When this became available.
    26 @suffix         This is a suffix comment.
    27 @throws         Document an exception.
    28 @todo           Describes todo information.
    29 @version        The entity version.

  Each directive is described in more detail in the following
  subsections.

  7.1 /** .. */

    Indicates javadoc style ccdoc comment that is associated with the
    next C++ statement (prefix style comment).

    A simple example is shown below:

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

  7.2 /**< .. */

    Indicates the beginning of a ccdoc style comment that is
    associated with the previous C++ statement (suffix style comment).

    A simple example is shown below:

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

  7.3 /*!< .. */

    Indicates the beginning of a ccdoc style comment that is
    associated with the previous C++ statement (suffix style comment).

    A simple example is shown below:

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

  7.4 //@{ .. //@}

    Specifies that a ccdoc comment is being specified using the '//'
    comment form as shown below:

      // ================================================
      //@{
      // This is a ccdoc comment.
      //@}
      // ================================================
      int foo();

    This pragma must exist by itself on the line.

  7.5 //@-

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

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

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

  7.6 ///<

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

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

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

  7.7 //!<

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

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

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

  7.8 /**@#-*/

    Turn off ccdoc token parsing. Unlike #ifndef __ccdoc__ this
    directive can be inserted anywhere. It is especially useful for
    excluding portions of code that confuse ccdoc.  Here is an example
    of how to use it:

      /**@#-*/
      #ifndef FOO
      insert random junk to generate a compiler error.
      #endif
      /**@#+*/

    This could also be done using the #ifndef pragma as follows:

      #ifndef __ccdoc__
      #ifndef FOO
      insert random junk to generate a compiler error.
      #endif
      #endif

  7.9 /**@#+*/

    Turn ccdoc token processing back on. See 7.10 for usage details.

  7.10 /**@#=<ch>*/

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

      7.10.1 This will confuse ccdoc.
        #define M(a) a=1;
        M
        M
        class XX;

      7.10.2 This will not confuse ccdoc because we insert semi-colons.
        #define M(a) a=1;
        M /**@#=;*/
        M /**@#=;*/
        class XX;

      7.10.3 Neither will this because we prep it out.
        #define M(a) a=1;
        #ifdef __ccdoc__
        M
        M
        #endif
        class XX;

      7.10.4 Or this because we put in redundant semi-colons.
        #define M(a) a=1;
        M;
        M;
        class XX;

  7.11 {@link <entity> <name>}

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

    You must specify both the entity and the link name.

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

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

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

    The example below shows how it is used:

      /**
       * Look at {@link #fct this} for more information,
       * you can also look at {@link #fct1 this} or {@link #fct2 this}.
       */
      void fct3();

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

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

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

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

  7.12 @@ <line>

    Translate HTML special characters for creating code fragments.

    Convert '<' to "&lt;" , '>' to "&gt;" and '&' to
    "&amp;". This is useful for inserting code fragments. Here is an
    example of how you would use this directive in a comment:

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

  7.13 @$ <entity> [<name>]

     Same as @link. See section 7.20 for detailed information.

  7.14 @author <name>

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

      /**
       * There are numerous authors.
       * @author Foo Bar
       * @author Spam Wombat
       */

    If an author is not specified for a package or a class, an entry
    is generated to an "unascribed" author.

    If there is more than one author, the best practice is to list
    them chronologically from most recent to earliest.

  7.15 @deprecated <description>

    Specifies that this interface has been deprecated. You should
    specify what to use as an alternative. The example below shows
    how to use this directive.

      /**
       * Get the system time.
       * @returns The system time.
       * @deprecated Use get_time_as_string to avoid memory bloat.
       */
      const char* get_time();

  7.16 @exception <name> <description>

    Deprecated. See @throws for usage information.

  7.17 @link <entity> [<name>] .. [@endlink]

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

    Here is an example of how it is used:

      /**
        * This class is closely associated with
        * @link Utils::Foo my class
        * and with this @link Utils::Spam my class @endlink and
        * with @link Utils::Wombat link to wombat
        * because they both do bar stuff.
        */

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

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

    The @endlink is optional. Note that in the wombat case, the string
    "link to wombat" is the link text.

  7.18 @param <name> <description>

    Describes a parameter to a function. There should be one @param
    directive for each argument. The example below shows how to use
    this.

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

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

    The contents of an @param directive can span multiple lines.  All
    lines following an @param directive are included until another
    ccdoc directive (other than @link and @@) is encountered.  The
    example below shows how this works:

      /**
       * This shows how @param can span multiple lines.
       * @param p1 This parameter can have a
       *@@         value < 10 and > 0. If the value
       *           is out of range, an exception is thrown.
       * @returns The associated record.
       */

  7.19 @pkg <name>

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

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

    The example below shows how to define the package directive.

      /**@pkg Stuff.Utils */

      /**@pkg Stuff::Utils */

      // This file is not part of any package.
      /**@pkg @null*/

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

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

  7.20 @pkgdoc <path> [<url>]

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

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

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

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

    The following example shows how to document several packages.

      // This file is not part of any package.
      /**@pkg @null*/

      /**
       * This is the documentation for the top of
       * the documentation tree.
       * @author The Build Team
       * @version 1.1
       * @pkg @top
       */

      /**
       * This is the top level package for MyProject.
       *
       * It does lots of useful things and contains
       * many other packages.
       * @author Ms. MyProject
       * @version 1.0
       * @pkgdoc MyProject
       */

      /**
       * This package contains the I/O utilities for
       * MyProject.
       *
       * This is the detailed information about the
       * I/O utilities package.
       * @author Mr. IO_Utilities
       * @version 1.1
       * @pkgdoc MyProject::IO_Utilities
       */

      /**
       * This package contains the string utilities for
       * MyProject.
       *
       * This is the detailed information about the
       * string utilities package.
       * @author Mr. String_Utilities
       * @version 1.2
       * @pkgdoc MyProject.String_Utilities http://mysite/String_Utilities.html
       */

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

  7.21 @pkgdoctid <name>

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

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

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

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

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

  7.22 @return <description>

    Deprecated, same as @returns.

  7.23 @returns <description>

    Describes the return value from a function. If there is no return
    value, do not use @returns. Ccdoc does not verify that you
    documented the return value correctly. Here is an example of how
    it is used.

      /**
       * Get the global value.
       * @returns The global value.
       */
       static int get_global_value();

    The contents of an @returns directive can span multiple lines.
    All lines following an @returns directive are included until
    another ccdoc directive (other than @link and @@) is encountered.
    The example below shows how this works:

      /**
       * This shows how @returns can span multiple lines.
       * @returns
       *@@ Return true if the value is < max or false if the value is >= max.
       * For more information about the value click
       *@link utils::value here @endlink .
       */

  7.24 @see <entity> [<number>]

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

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

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

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

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

      /**
       * Generate three links, one to the class named Foo,
       * the second to the second overloaded method
       * Spam in the Bar class and the third to a document
       * called wombat at the specified URL.
       * @see Foo
       * @see Bar::Spam 2
       * @see <a href=wombat.html>wombat</a>
       */

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

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

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

  7.25 @since <version>

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

    The example below shows how to use this directive.

      /**
       * This is a new function.
       * It does really new stuff.
       * @author Foo Bar
       * @version 1.0
       * @since v1.2 Built: 2001/10/01
       */
      void fct();

  7.26 @suffix

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

      class Foo {
      public:
        /**
         * This is the traditional prefix comment form.
         */
        void traditional_comment_form();

        //@{
        // This is an alternate prefix comment form.
        //@}
        void alt_prefix_comment_form();

        void traditional_suffix_comment_form();
          //@{
          // This is the new suffix comment
          // form that some folks have requested.
          // @suffix
          //@}

        void alt1_suffix_comment_form();
          /**<
           * This is a doxygen compatible suffix comment
           * form that some folks have requested.
           */

        void alt2_suffix_comment_form();
          /*!<
           * This is a doxygen compatible suffix comment
           * form that some folks have requested.
           */

        void alt3_suffix_comment_form(); //@- Short comment.
        void alt4_suffix_comment_form(); ///< Short comment.
        void alt5_suffix_comment_form(); //!< Short comment.
      };

    The alternative forms (1,2,4,5) are generally preferred for 
    doxygen compatibility.

  7.27 @throws <name> <description>

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

      /**
       * This function does stuff.
       *
       * Here is more detail about the stuff
       * it does.
       * @param name The name of the object.
       * @returns The object.
       * @exception Exception_NullParameter Is thrown
       * if name is NULL.
       */
      SomeObject GetObject(const char* name);

    The contents of an @exception directive can span multiple lines.
    All lines following an @exception directive are included until
    another ccdoc directive (other than @link and @@) is encountered.
    The example below shows how this works:

      /**
       * This shows how @exception can span multiple lines.
       * @exception Port::Exception Is thrown when the program
       * runs out of disk space.
       */
      void use_disk_space();

  7.28 @todo <description>

    Specifies that there are additional things things to be done to
    this interface or its implementation. The example below shows
    how to use this directive.

      /**
       * Get the full file by name if it exists.
       * @param out The output file name.
       * @param in The input file name.
       * @returns The full file name of the first file that matches
       *          the name parameter. If no match is found, an empty
       *          string is returned.
       * @author Foo
       * @version 1.0
       * @todo Support wild cards in the input name.
       */
       void get_full_file_name(string& out,const string& in);

  7.29 @version <id>

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

8 Comment Format

  The basic comment format is as follows:

    Format                    Description
    ========================  ===================================
    /**                       Start of comment.
     * <brief description>    The brief description is terminated
     *                        by a period followed by a tab, space
     *                        or newline or it is termined by a
     *                        directive. This complies with the
     *                        javadoc syntax.
     *
     *                        In older versions of ccdoc the brief
     *                        description was termined by a blank
     *                        line. This behavior can be re-enabled
     *                        by specifying the phase 1 -nojdsds
     *                        switch.
     *                        First blank (all w/s) line.
     *
     * <full description>     Any number of lines with blanks.
     */                       End of comment.
    <C++ entity>              The entity that the comment is
                              associated with (unless it is
                              a pkgdoc comment).
    ========================  ===================================

  Each blank line, other than the first one, is treated as a an HTML
  paragraph (<p>). The first blank line separates the brief
  description from the full description in -nojdsds mode otherwise it
  is ignored.

  Ccdoc directives can be embedded anywhere in either description but
  they must be the first entity on the line.

  The full description is optional.

  The leading asterisk on each line is optional.

  8.1 The simplest possible comment

    The example below shows the simplest possible comment forms.

      /**Get the age of an employee.*/
      unsigned int age(const char* name);

      //@{ Get the birthdate of an employee. //@}
      unsigned int birthdate(const char* name);

      unsigned num_items(); //@- The number of items.
      unsigned num_items1(); ///< The number of items.
      unsigned num_items2(); //!< The number of items.
      unsigned num_items3(); /**< The number of items. */
      unsigned num_items4(); /*!< The number of items. */

  8.2 A more reasonable example.

    The example below shows a more complete example for the function
    in 8.1. As you can see, it assumes that age is part of a class or
    a namespace called Employee.

      /**
       * Get an employees age.
       * This function is not thread safe because it
       * uses statically initialized data.
       *
       * If the age of the employee is not known, return
       * the value 0. The example below shows how to use
       * this function.
       * <blockquote>
       * <pre>
       *@@ #include <iostream>
       *@@ #include "Employee.h"
       *@@ int main(int,char**) {
       *@@   cout << "John Doe's age is" 
       *@@        << Employee::age("John Doe")
       *@@        << endl;
       *@@   return 0;
       *@@ }
       * </pre>
       * </blockquote>
       * @param name The name of the employee.
       * @returns The age of the employee or zero if the
       *          age if the employee is not known.
       * @see Employee
       * @throws MyExceptions::NullArgException
       *         if the name argument is NULL.
       * @todo Modify this function to accept a std::string
       *       reference argument to avoid having to check
       *       for a NULL argument.
       */
       unsigned int age(const char* name);
      
  8.3 Alternative comment form 1

    Ccdoc allows you to use the C++ single line comment form in
    several ways. In this form you specify the beginning and ending of
    a comment by using the standard form and prepending the '//'s as
    shown below:

      ///**
      // * This is a simple comment.
      // */
      int simple;

  8.4 Alternative comment form 2

    This form allows you do away with the multi-line comment form
    entirely by specifying the ccdoc comments using begin and end
    directives as shown in the example below:

      // ================================================
      //@{
      // This is a simple comment for foo that uses the
      // new single line comment form.
      //@}
      // ================================================
      int foo();

  8.5 Alternative comment form 3 (suffix)

    This form allows you to specify complex ccdoc comments for the
    previous C++ statement as shown in the example below:

      int foo();
        //@{
        // This is a simple comment for foo().
        // @suffix
        //@}

      int foo1();
        /**<
         * This is a simple comment for foo1().
         */

      int foo2();
        /*!<
         * This is a simple comment for foo2().
         */

  8.6 Alternative comment form 4 (single line, suffix)

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

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

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

9 Package Help

  This section describes how to link to ccdoc comments from your
  documentation tree. The root level file is ccdoc.root.pkg.html. The
  'root' package name can be changed using the -root <name> switch.

  In the previous system the root level file was called
  ccdoc.index.html. That behavior can be mimic'ed by using the
  -rootfile ccdoc.index.html switch.

  Here is an example that shows how to create documentation for a
  system:

    % cat src/rootdoc.txt <<END
    /**
     * This is the root level documentation.
     * @author The Team
     * @version 1.2
     * @pkgdoc @root
     */
    END
    % ccdoc -db sys.db \
         -pkg system \
         -html web/ \
         -rooturl http://system/index.html \
         -srcurl http://system/src/ \
         src/rootdoc.txt \
         src/*.h

  Here is another example that shows how to create documentation for a
  system with a ccdoc.index.html root file:

    % cat src/rootdoc.txt <<END
    /**
     * This is the root level documentation.
     * @author The Team
     * @version 1.2
     * @pkgdoc @root
     */
    END
    % ccdoc -db sys.db \
         -pkg system \
         -html web/ \
         -rootfile web/ccdoc.index.html \
         -rooturl http://system/index.html \
         -srcurl http://system/src/ \
         src/rootdoc.txt \
         src/*.h

  Note that the root file: "http://system/index.html" is NOT
  generated by ccdoc.

  Also note that the -srcurl tells the browser where to find the
  source code.

  Each generated documentation file will have a link named 'Home' to
  the root url 'http://system/index.html'.

  The http://system/index.html can have a link to
  web/ccdoc.root.pkg.html to access the ccdoc documentation.

************************************************************************
**                           HELPFUL HINTS                            **
**                                                                    **
**  To capture this message in an output file called help.log,        **
**  run this command as:                                              **
**                                                                    **
**    ccdoc -log help.log -nocout -h                                  **
**                                                                    **
**  If you just want to know how to run ccdoc, see section 6 of this  **
**  help message.                                                     **
**                                                                    **
**  If you just want to see some comment examples, see section 8 of   **
**  this help message.                                                **
**                                                                    **
************************************************************************