cd "c:\DocumentationTools\CPlusPlusDoc"

CPlusPlusDoc

Linux/Unix:

cd /DocumentationTools/CPlusPlusDoc"

CPlusPlusDoc

 

Using the Program:

After starting "CPlusPlusDoc", you will be shown the following:

"Please enter the absolute path to the parent directory of all header files and subdirectories:"

"Enter here:"

If, for instance, you have all your source code files in the "c:\sourceCode\headerFiles" on a Windows machine or the "/sourceCode/headerFiles" on a Linux/Unix machine, you would enter the following:

Windows:

c:\sourceCode\headerFiles

Linux/Unix:

/sourceCode/headerFiles

You will then be asked if you would like to document private class members:

"Do you want to document private class members:"

"Enter here:"

If you would like to document private class members, answer "yes" or "y", and if you don't, answer "no" or "n".

CPlusPlusDoc will then collect all the absolute paths of every file listed in the "headerFiles" directory, along with all the files in its sub-directories. All header files with a ".h" extension are then parsed through and searched for class definitions, each for which CPlusPlusDoc generates an HTML file.

CPlusPlusDoc generates a "docs" directory under the "headerFiles" directory, and places all documentation in this directory. CPlusPlusDoc creates a few files for its own use in the "docs" directory, and also produces an "index.html" file that is most useful for a developer because its layout allows him/her to easily navigate through all generated HTML files by providing links to each file. CPlusPlusDoc generates a "log.txt" file that details the number of classes, inner structures, and inner unions having been documented, along with a listing of each class that was documented and the header file it came from. CPlusPlusDoc also includes a commented line near the top of the HTML code in the HTML file it produces that lists the absolute path to the header file the HTML file is produced from.

 

How to Document Source Code:

Just like javadoc's comments, CPlusPlusDoc comments begin with a "/**" and end with a "*/". The only comments processed are those appearing immediately before a class element is processed, so you must include all relevant information inside one comment block.

Here is a simple example of a member method declaration with CPlusPlusDoc comments:

/**
* This function deposits the number of dollars represented by
* <b>amount</b> into the bank account represented by the
* <b>accountNumber</b> argument. Continued work on this
* function is needed because no one has gotten
* it to work in real life. If you get it to work, please email
* me with the implementation so I can put it inside an infinite
* loop with my account information in it!
*
* @param accountNumber The bank account number to which the amount
* is to be deposited.
*
* @param amount The amount to be deposited.
*
* @return True if the deposit was successful, false if not.
*/
bool depositMoney(int accountNumber, float amount);

Notice the use of "<b>" and the "</b>" in the above comment. Since the documentation produced is in HTML, you are free to use HTML tags wherever you like in your comments and it will be reflected in the documentation.

 

CPlusPlusDoc comment-tags:

@param <parameter name>             
	Used to detail parameters
	Example: @param stringOne The string to search.

@return                             
	Used to detail the return value from a function
	Example: @return True if successful, false if not.

@throws <exception name>            
	Used to detail the exception a function throws
	Example: @throws URLException Throws a URLException object if the URL is invalid.

@exception <exception name>         
	Used to detail the exception a function throws (same as the above tag)
	Example: @throws URLException Throws a URLException object if the URL is invalid.

@author                             
	Used to detail the author of the class or class member
	Example: @author Ram Dass

@co-author                          
	Used to detail the co-authors of the class or class member
	Example: @co-author Erich Fromm

@version                            
	Used to detail the version of the class or class member
	Example: @version 1.00

@deprecated                         
	Used to mark a class or class member as being deprecated
	Example: @deprecated Since Version 1.00

@since                              
	Used to detail the date this class or class member first appeared
	Example: @since Version 1.00

@precondition                       
	Used to list a precondition for the class method
	Example: @precondition Just list a precondition here...I think you get how it works.

@postcondition                      
	Used to list a postcondition for the class method
	Example: @postcondition Do I need to explain?

{@link NamespaceName::ClassName}    
	Used to create an HTML link to the class within the namespace
	Example: {@link std::iostream}

{@link ClassName}                   
	Used to create an HTML link to the class
	Example: {@link ClassComponent}


*Note: If the class falls within a namespace, the {@link NamespaceName::ClassName} form must be used. 

An example of nearly every one of the above tags can be seen in the source code header files for the "CPlusPlusDoc" tool, and the documentation produced from running the tool against these header files can be found in the "docs" directory contained in the "CPlusPlusDoc" download.

 

#ifdef STP_NAMESPACE
namespace STP {
#else
namespace GLL {
#endif      

namespace name + "-" + directory path + "A###" + "OuterClassName" + "+" + "InnerClassName" + ".h"