home     download     screen shots     bugs     mailing list     example output     generated MFC docs     help     faq     tools and utilities

CppDoc Help


Contents

  1. Introduction
  2. Main Dialog
  3. Documentation Comments
  4. Command Line
  5. Privacy



Introduction

Welcome to CppDoc. The idea behind this application is simple: it generates HTML documentation for your C++ classes, based on your source code and special comments embedded within it.

CppDoc parses source-code comments that start with "/**". So, it will associate the comment "This is only a test." with the class Foo in the following example: 

    /**
     * This is <I>only</I> a test.
     */
     class Foo
     {
         ...
     };

CppDoc recognizes and documents classes, member functions, member data, global functions, typedefs, and enums. The documentation comments are optional; if you leave them out, CppDoc will still generate a nicely-formatted set of documentation based on your class hierarchy and class members.

Two modules are included with CppDoc: the original one, which produces v1.0 output, and a new one which produces full Javadoc-like output and which supports Javadoc tags, such as @see , @return , etc.

That's pretty much all there is to it. See the Help section of the main dialog for more details.


Free

CppDoc is free, and may not be sold. It may be included with CD-ROM/DVD-ROM distributions that carry nominal charges for the media. It may be distributed freely on any website or through any other distribution mechanism, as long as no part of it is changed in any way, and as long as its ReadMe file remains with it. This program is offered "AS IS", with no warranties of any kind.

If you like If you like CppDoc, or if you have a request for a bug fix or enhancement, please submit it here. You can sign up for the mailing list here. Finally, if you would like to donate to CppDoc, visit www.cppdoc.com/donate.html.


Back to top



CppDoc Main Dialog
(Windows version only)

Title

The main title that will be used throughout the generated documentation.


Company name
Modules may use this in the generated documentation.


HTML header
This HTML code will be included at the beginning of each generated page. You can enter either an HTML fragment or the name of a file whose contents will be pasted into the header.


HTML per item
This HTML code (HTML fragment or filename, as above) is used as a template for each C++ class on the index frame (not in the class details pages). The following variables may be included:
You can use this feature to customize the entire index frame; for example, you could enter the following code:
class <b>$C</b><blockquote>$D</blockquote><br>
This would produce output like the following:
class Database
Encapsulation for an ODBC-accessible database.
class Query
This class represents a SQL query that can be fed to Database .
...
Also, you can mark an entire section to be skipped when a particular variable is missing. To do this, just put "!variable-name" at the beginning and end of the section. For example:
<b>$C</b>: primary source file is $F!G, secondary is $G!G.<br>
This would produce output like the following:
Database: primary source file is Database.h, secondary is Database.cpp.
Query: primary source file is Query.h.
...

HTML footer
This HTML code (HTML fragment or filename, as above) will be included at the end of each generated page.


Source code links
CppDoc can include links to source code in the class details pages. Source code links will be prepended by this path. For example, if you fill in "http://localhost/working/src" here, then a link to "foo.cpp" in the documentation will be "http://localhost/working/src/foo.cpp". If you choose the Default option, CppDoc will generate an HTML file for each source code file, and link to that.


"In index frame, print class list hierarchically"
When checked, the classes in the index will be indented according to their hierarchy, rather than being listed in strict alphabetical order.


"Append <BR> to each documentation line"
A "<BR>" tag will be added to the end of each new line of documentation (within a documentation comment started by "/**").


Input
Enter list of files or directories to process here. Separate items by spaces or returns, and put double-quotes around files or directories with spaces in their names. Note: by default, CppDoc uses the directory name as the project name. You can change the project name by adding "=<project-name>" to the path. So in the following example, code in the directory "include" will be put into a project called "MFC":
"c:\program files\microsoft visual studio\vc98\mfc\include=MFC"
You can also exclude individual subdirectories by prefixing them with '#', e.g.,
/working/includeme
#/working/includeme/skipme


 Output (Main HTML page)
The name of the master HTML file that will be generated.


Options
Other Options (dialog)

Back to top




Documentation Comments

Basic format
Documentation comments begin with "/**" and end with "*/". Preceding a class, struct, typedef, enum, variable, or function with a documentation comment will cause the contents of the comment to be attached to that entity. Comments can include HTML formatting. For example, the following comment is valid:
/**
* This is a <B>test</B> of:
* <UL>
* <LI>documentation comments
* <LI>HTML formatting
* </UL>
*/
void foo()
{
}
It will attach this documentation to foo():
This is a test of:

Special tags for the cppdoc-standard module
The cppdoc-standard module processes a number of special tags when they are found at the beginning of a line within a documentation comment. These tags should be used below normal documentation text.
Examples:
@see <a href="http://www.cppdoc.com">CppDoc website</a>
@see "The Reference Manual"
@see parser.ParserExpression#eval(int)
@see ParserExpression#eval the illustrious eval function
@see ParserExpression
@see #eval the one-and-only eval (this is display text)
The following "floating tags" may be used anywhere in the documentation comment, unlike the others which must appear at the beginning of a line.
/**
* Click {@link ParserExpression#eval here} to go
* to the eval() function in the ParserExpression
* class.
*/

Excluding files from processing
If you include the special comment
/**NODOCUMENT**/
at the beginning of a file, it will not be included in processing.


Excluding parts of files from processing
To exclude parts of a file from processing, put the following comment at the beginning of the section to be excluded: 
/* CPPDOC_BEGIN_EXCLUDE */
Put the following comment at the end of the section to be excluded: 
/* CPPDOC_END_EXCLUDE */

Including project-level and overview-level documentation
The cppdoc-standard module allows you to include documentation for each project, and overview documentation.  To create project-level documentation, create a file called "project.html" at the root for that project's source code.  For overview documentation, create a file called "overview.html" at the overall root directory to be processed.  These filenames may be changed in the Module Options dialog, or as command-line flags for the cppdoc-standard module.


Back to top




CppDoc Command Line

Usage
cppdoc [flags] directory|file[=project-name] [...] output-filename
cppdoc_cmd [flags] directory|file[=project-name] [...] output-filename


Description
CppDoc accepts a space-separated list of source-code directories to process. The last argument is the output filename for the HTML class index. If you only provide one argument, CppDoc will create a file called "index.html". Note: by default, CppDoc uses the directory name as the project name. You can change the project name by adding "=<project-name>" to the path. So in the following example, code in the directory "include" will be put into a project called "MFC":
"c:\program files\microsoft visual studio\vc98\mfc\include=MFC"

Flags
/**
 * Example comment.
 */
This option also optionally accepts a second (alternate) set of strings, which define an additional documentation format using "//"-style comments. For example, the setting "/**;*;*/;///;///;///" will accept the following style in addition to the one shown above:
///
/// Example comment.
///

The comment specification can be set up to allow multiple comment formats.  The setting "//=-;//;//=-" will accept both of the following styles:
//=
// Example comment.
//=

//-
// Example comment.
//-
                   
Note that the last character of the start string may be repeated, so the setting "//=;//;//=" will accept the following style:
//=================
// Example comment.
//=================
Also note that the "//" comments can be on a single line, e.g.,
/// Example comment.
int foo;
Finally, if you put the string "AFTER" in front of a documentation comment format (e.g., "AFTER///;///;///"), then documentation comments are read after their associated declarations, like this:
int foo;    /// a documentation comment

Flags for the cppdoc-standard module
You can include these flags when you have selected "cppdoc-standard" as the module. For boolean values, you can optionally use "=false" or "=true".

Generating a Command Line
You can generate a command line from the settings in the current dialog by choosing "Generate Command Line…" from the system menu (the menu with "Close" and "About CppDoc").


Pure Command Line Interface
CppDoc includes an executable (“cppdoc_cmd.exe”) which does not bring up the dialog and which writes to standard output. It takes the following additional options:

Example

CppDoc title="My Class Documentation" company="My Company" hier autorun overwrite classdir=projects sourcedir=/doc/src autoquit autoview module cppdoc standard enable author enable deprecations=false d:\working\utils d:\projects c:\temp\doc.html

Back to top

Privacy

CppDoc never, ever collects or sends any information about you without your knowledge. If you send an email to me using the Feedback button, CppDoc sends me the name you type, the return address you type, your comments, and whether or not you checked "Please include me on the mailing list for new versions."

When you use CppDoc’s Update feature to check for a new version, or if you enable auto-update, no information about you is ever sent to the server (CppDoc just reads a static file through http). The auto-update feature is turned off by default.

Back to top


 © 2001 Richard Feit. All rights reserved.