ccdoc(1)ccdoc(1)NAMEccdoc - C++ interface documentation tool
SYNOPSISccdoc [db file ] [ -switches ] ...
OR
phase1: ccdoc [-db file ] [ -phase1_switches ] header_file1 ...
phase2: ccdoc [-db file ] [-index]
phase3: ccdoc [-db file ] [-html directory/ ] [ -phase3_switches ]
DESCRIPTIONccdoc automatically generates HTML web documentation from C++ programs
by parsing the source file headers. It was designed to aid collabora‐
tion between package users and package developers by documenting the
interface.
The source code for this program is provided free charge from
http://ccdoc.sourceforge.net.
The program operates in three phases. The first phase translates the
C++ files to an intermediate format that is stored in the db file. It
is usually run multiple times over header files in different directo‐
ries and is called the input phase. This phase automatically recog‐
nizes the C++ structure to create the documentation but you can add
additional comments by using directives that have a javadoc like syn‐
tax.
The second phase cross indexes all the parsed entities and is called
the index phase.
The third phase generates the HTML and is called the output phase.
Detailed information about the switches, program phases and comment
syntax can be found in the on-line help or in the users manual at
http://ccdoc.sourceforge.net.
OPTIONS
To understand how to use the options for the different phases, see the
on-line help or the users manual at http://ccdoc.sourceforge.net.
-D<name>[=<value>]
Define a macro and, optionally, define its value.
Phase: parse
-U<name>
Undefine a macro.
Phase: parse
-args Dump the command line arguments. This is enabled automatically
in verbose (-v) mode.
Phase: all
-bg <color>
The background color. The default is the default for the
browser.
Phase: output
-[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.
Phase: parse
-cid Deprecated. Same as -verbose.
Phase: all
-ctf <file>
Deprecated. Same as -db.
Phase: all
-db <file>
The name of the ccdoc database.
Phase: output
-dospaths
The file paths contain backslashes that need to be converted to
forwards slashes for HTML.
Phase: output
-[no]doxygen
Enable limited doxygen compatibility mode. The default is -doxy‐
gen. 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.
Phase: parse
-fg <color>
Same as -fgtext.
Phase: output
-fglink <color>
The foreground link color. The default is the default for the
browser.
Phase: output
-fgtext <color>
The foreground text color. The default is the default for the
browser.
Phase: output
-fgvlink <color>
The foreground vlink color. The default is the default for the
browser. These are used links.
Phase: output
-files <list>
Designates a file that contains the list of files to parse.
Phase: parse
-h,-help
Displays the extensive on-line help and exits. The on-line cov‐
ers the different program phases, the comment directives and the
program switches.
Phase: all
-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.
Phase: output
-htm <prefix>
Same as -html <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.
Phase: output
-imageurl <URL>
Same as -imgurl <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.
Phase: output
-index Generate the indices.
Phase: index
-[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.
Phase: parse
-log <file>
All information output by the program is also sent to the speci‐
fied log file. Multiple log files can be specified. By default
all output is sent to cout.
Phase: all
-[no]macros
Deprecated. Same as -[no]rptmac.
Phase: output
-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 check‐
sum is added to guarantee that the file name is unique. If max‐
pathlen is set to zero, no limit checking is performed.
Phase: output
-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.
Phase: output
-nocout
Turn off output to cout. This is used to test the help output
without displaying anything to the console.
Phase: all
-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.
Phase: parse
-[no]private
Deprecated. Same as -[no]rptpri.
Phase: output
-[no]protected
Deprecated. Same as -[no]rptpro.
Phase: output
-[no]public
Deprecated. Same as -[no]rptpub.
Phase: output
-putenv <env>
Set an environment variable from the command line. This is use‐
ful for setting up regression tests in scripts on various plat‐
forms.
Phase: all
-root <name>
Change the name of the root package from 'root' to something
else.
Phase: output
-rootfile <name>
Change the top level output file name from <pre‐
fix>ccdoc.root.pkg.html to whatever the user wants. This can be
used to create the ccdoc.index.html file by specifying: -root‐
file ccdoc.index.html. This switch allows you to completely
specify the path. The -html prefix is ignored.
Phase: output
-rootpurl
<URL>
Phase: output
-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.
Phase: output
-[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.
Phase: output
-[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.
Phase: output
-[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.
Phase: output
-rptctcs <string>
Allow the user to specify the Content-Type char set. This allows
international languages to be supported. The default char set is
Phase: output
-rptdefa <string>
Set the default string for the author field in top level enti‐
ties. The default is
Phase: output
-rptdefasd <string>
Set the default string for the automatically generated short
description field in top level entities. The default is
Phase: output
-rptdefsd <string>
Set the default string for the short description field in top
level entities. The default is
Phase: output
-rptdefv <string>
Set the default string for the version field in top level enti‐
ties. The default is
Phase: output
-[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.
Phase: output
-[no]rptdpd
If the package description is not specified, report the descrip‐
tion as unknown. The default is -norptdpd which tells ccdoc to
ignore descriptions on packages unless they are explicitly spec‐
ified.
Phase: output
-[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.
Phase: output
-[no]rptfwcf
The fixed width code font switch. Use a fixed width font when
reporting code fragments. The default is -norptfwcf.
Phase: output
-[no]rpthpc
Report package contents hierarchically like the the class sum‐
mary page. The default is -rpthpc.
Phase: output
-[no]rptim
Report all inherited methods as though they were defined
locally. The default is -rptim.
Phase: output
-[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 use‐
ful.
Phase: output
-[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.
Phase: output
-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> char‐
acters 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.
Phase: output
-rptmlcifi <num>
Maximum length of the contents
When the string exceeds this length, only the first <num> char‐
acters are printed followed by .. to indicate truncation.
The default length is 32. A value of zero means don't impose the
limit.
Phase: output
-[no]rptpri
Report private items. The default is -norptpri.
Phase: output
-[no]rptpro
Report protected items. The default is -norptpro.
Phase: output
-[no]rptpub
Report public items. The default is -rptpub.
Phase: output
-[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.
Phase: output
-[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 gener‐
ated.
Phase: output
-[no]rpttyp
Report typedefs. Default is -rpttyp.
Phase: output
-[no]rptun
Report unions. Default is -rptun.
Phase: output
-sourceurl <URL>
Same as -srcurl <URL>.
-srcurl <URL>
The URL where the source files can be found. If this is speci‐
fied, hyperlinks are created for Source entries.
Phase: output
-[no]tcms
Turn on or off the processing of template class methods that are
defined outside of the class declaration.
Phase: parse
-trailer <file>
The HTML used for the customized trailer.
Phase: output
-[no]typedefs
Deprecated. Same as -[no]rpttyp.
Phase: output
-[no]unions
Deprecated. Same as -[no]rptun.
Phase: output
-[no]v Turn verbose mode on or off. The default is off.
Phase: all
-version
Report the program version. The version contains the program
name, the version, the revision, the release date and the compi‐
lation id. Here is an example of what -version reports: % ccdoc-versionccdoc v08r41 2004/09/29 bin_opt_msvc_MSWin32-multi-
thread-4.0
Phase: all
-[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.
Phase: all
-[no]warn
Turn warnings on or off. The default is on.
Phase: all
DIRECTIVES
These are the directives that drive the output format. They are found
in the comments associated with the entities. The basic format is:
/**
*<brief_description>
*<long_description>
*<directives>
*/
Where the brief description is a single sentence terminated by a
period, the long description is anything else, including HTML tags and
the directives are special ccdoc tags.
These comments are associated with C++ entity declarations for classes,
variables, functions, enumerated types and typedefs as shown in the
simple example below for a class.
/**
* Briefly, do important foo stuff.
* Long winded, do really important foo stuff.
* @author Ima Programmer
* @version 1.2
* @see Bar
* @see Spam
*/
For more information about the directives see the on-line help or the
users manual at http://ccdoc.sourceforge.net.
/** .. */
Encloses a javadoc style ccdoc comment.
/**< .. */
Encloses a doxygen style suffix ccdoc comment.
/*!< .. */
Encloses a doxygen style suffix ccdoc comment.
//@{ .. //@}
Encloses a ccdoc comment for C++ style line comments.
//@- Single line suffix C++ style comment form.
///< Same as //@- (doxygen compatible).
//!< Same as //@- (doxygen compatible).
/**@#-*/
Turn off ccdoc token parsing.
/**@#+*/
Turn on ccdoc token parsing.
/**@#=<ch>*/
Insert <ch> into the input stream.
{@link...}
The in-line link specification.
@@ Translate HTML special characters for code fragments.
@$ Same @link.
@author
Specify an author.
@deprecated
Describes the alternatives to use.
@exception
Deprecated, same as @throws.
@link,@endlink
Generate a hyperlink to a ccdoc entity.
@param Document a function or class method parameter.
@pkg Specifies the name of a package.
@pkgdoc
This comment documents a specific package.
@pkgdoctid
Redefine the output title id for a pkgdoc.
@return
Deprecated, same as @returns.
@returns
Documents the return value from a method or function.
@see Add a hyperlink entry to the See section.
@since When this became available.
@suffix
This is a suffix comment.
@throws
Document an exception.
@todo Describes todo information.
@version
The entity version.
AUTHOR
Joe Linoff
LICENSEhttp://ccdoc.sourceforge.net 2004/09/29 ccdoc(1)