NAME

cceExtHtml - Extract HTML documentation from C++ source and header files

SYNOPSIS

cceExtHtml [ -t title ] [ --title title ] [ --prefix dir ] [ -f ] [ --fields ] [ -v ] [ --version ] [ -h ] [ --help ] files

DESCRIPTION

cceExtHtml extracts HTML documentation from C++ source and header files. It understands a subset of C++ (the main difference is that types of members and method arguments must be ``simple''), and looks for specially-formatted comments in certain places.

OPTIONS

-t title
--title title
Specify the title of the system being documented.

--prefix dir
Write files to the given directory. Defaults to the current working directory.

-f
--fields
Print the list of recognized comment fields.

-v
--version
Print version information.

-h
--help
Print command usage information.

EXAMPLES

Extract documentation from all source and header files in /users/ptolemy/src/kernel

% cceExtHtml --title "The Ptolemy Kernel" /users/ptolemy/src/kernel/*.{cc,h}

CODING STYLE

cceExtHtml parses a subset of C++, recognizing class and structure declarations and method definitions. The contents of function bodies, enumeration, typedef and extern declarations are ignored. Comments are first-class entities, limiting where they may appear in class declarations outside function bodies. In particular, a comment immediately preceding a public:, protected:, or private: declaration within a class definition is considered a syntax error.

In general, place all comments before the entity they comment. In particular, cceExtHtml will mistakenly associate a comment after a variable declaration on the same line with the next entity. Comments within function arguments are the one exception to this rule, which much appear after the agument, but before the comma that separates it from the next argument.

When both a declaration and a definition of an entity, such as a method, appear, the comment for the definition takes precedence.

Comments may be of two forms: old-style comments, which are surrounded by /* */, and new-style comments, which are one or more lines that begin with //. By default, the text within these comments is interpreted as a short synopsis of the entity it precedes. Additional fields within a comment are denoted by a keyword starting with an at-sign. The text associated with a field starts immediately after the keyword and continues until the next such keyword or until the end of the comment. Invoke cceExtHtml with the --fields option to see the list of recognized fields.

Some sample comments are shown below


// A short synopsis in a new style comment

// A one-sentence description
//
// @Description With a longer, potentially multi-line
//              description below it in a new-style
//              comment block

/* Normal old-style comment */

/******************************

  Example of ignoring asterisks

  @Description Asterisks immediately after the start or immediately
               before the end of an old-style comment are ignored.

  @Author Stephen Edwards

 ******************************/

cceExtHtml only parses a subset of C++. In particular, the types it recognizes must be ``simple.'' A class variable, function argument, or return type must be either a simple scalar, a class, or a type from a typedef. Additionally, the type may be a pointer (of any depth, e.g., a pointer to a pointer) to, a reference to, or a one-dimensional array of any of these simple types. More complex types (e.g., function types, multi-dimensional arrays) should be typedefed.

Each variable declaration within a class definition may only declare a single variable, e.g., int a,b; is not permitted, but int a; int b; is.

AUTHOR

Stephen Edwards
University of California, Berkeley
sedwards@eecs.berkeley.edu
Generated on 7 March 1997 by cce