|
Unix VPS
Support
FAQ
Network
Miscellaneous
|
| ccdoc(1) | FreeBSD General Commands Manual | ccdoc(1) |
NAME
ccdoc - C++ interface documentation toolSYNOPSIS
ccdoc [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 ]
DESCRIPTION
ccdoc automatically generates HTML web documentation from C++ programs by parsing the source file headers. It was designed to aid collaboration between package users and package developers by documenting the interface.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 directories and is called the input phase. This phase automatically recognizes the C++ structure to create the documentation but you can add additional comments by using directives that have a javadoc like syntax.
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 -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.
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 covers 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 specified 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 checksum is added to
guarantee that the file name is unique. If maxpathlen 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 useful for
setting up regression tests in scripts on various platforms.
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
<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.
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 entities. 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 entities. 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 description as
unknown. The default is -norptdpd which tells ccdoc to ignore descriptions
on packages unless they are explicitly specified.
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 summary 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 useful.
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> 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.
Phase: output
- -rptmlcifi <num>
- Maximum length of the contents
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.
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 generated.
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 specified,
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 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
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 LinoffLICENSE
| 2004/09/29 | http://ccdoc.sourceforge.net |
Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.