$Id: faq.txt,v 1.2 1999/06/14 12:44:25 jdl Exp $ ================================================================ CONTENTS 1.0 What is CcDoc? 1.1 What is the latest version? 1.2 How much does it cost? 1.3 What support options are available? 1.4 What other documentation packages are available? 2.0 Getting CcDoc 2.1 Where can I get CcDoc for Windows NT/98? 2.2 Where can I get CcDoc for Solaris? 2.3 Where can I get CcDoc for HP? 2.4 Where can I get CcDoc for Linux? 2.5 Where can I get CcDoc for AIX? 2.6 How do I unpack CcDoc binaries under unix? 2.7 How do I unpack CcDoc source code under unix? 2.8 How do I unpack CcDoc binaries under Windows? 2.9 How do I unpack CcDoc source code under Windows? 3.0 Building CcDoc 3.1 What tools do you use? 3.2 What is the directory structure? 3.3 How do I build CcDoc? 3.4 How do I backup CcDoc? 3.5 What revision control system do I use? 4.0 Running CcDoc 4.1 What does phase 1a do? 4.2 What does phase 1b do? 4.3 What does phase 2 do? 4.4 What does phase 3 do? 4.5 What are the CcDoc switches? 4.6 What environment variables does CcDoc recognize? 5.0 What is the CTF file? 5.1 How do I merge CTF files? 6.0 Documentation Tips 6.1 What is the basic comment syntax? 6.2 What CcDoc directives are available? 6.3 How do I tell CcDoc to ignore sections of code? 6.4 How do I document the root level? 6.5 How do I document a package? 6.6 How do I embed references to third party tools like RogueWave? 6.7 How do I document a class? 6.8 How do I document a method? 6.9 How do I document a variable? 6.10 How do I document an enumerated type? 7.0 Miscellaneous 7.1 How do I embed hyperlinks to CcDoc generated targets in v0.7 and later? 7.2 Can I embed my comments in the source file rather than the header file? 7.3 Does CcDoc support '//' style comments? 7.4 How can I embed code fragments in my documentation? 7.5 How do I customize the trailer? ================================================================ 1.0 Introduction CcDoc tool is a javadoc like tool that automatically generates web documentation from C and C++ programs by parsing the source file headers (interface definitions). The latest versions (v0.7a or later) can also extract documentation from from implementation files (.cpp). It was written because I write code in both Java and C++ and wanted a consistent interface for both. I tried very hard to stay true to the javadoc syntax and tool flow but, because of language differences I was forced to change (or add) a few things. With this tool you do not have to explicitly specify classes, methods or variables, the parser figures them out which means that it works whether or not you have embedded comments. This capability allows CcDoc to be run over code with a different comment style (or no comment style) to build basic web pages that document classes in a set of packages. You can add documentation later. One unique aspect of CcDoc is that it tries to understand the program before pre-processing. This allows you to comment macro definitions but makes the parsing problem much harder. If you are interested in being added to my CcDoc mailing list, please send me e-mail at jlinoff@ix.netcom.com. 1.1 What is the latest version? The latest version of CcDoc is v0.7a, released June 1999. 1.2 How much does it cost? This tool is free software with no express or implied warranty. You are free to copy and modify it but you must keep the copyright and permissions notices intact. Starting with v0.8, CcDoc will be provided as shareware for $20.00 per copy. The source code will still be provided as part of the release and you can still download the program and try it at no cost. The only difference is that I am asking that you send me a small fee if you find the program useful so that I can continue to develop and support it. 1.3 What support options are available? I have received a number of e-mails asking about what support options are available so I will present the range of options after I have said a few things. My intent here is NOT to make money but to encourage everyone to use the free internet resources The last option is presented because several companies have contacted me about an option that they can pay for. Here they are in my order of preference: Option COST Description ====== ==== =============================== 1 FREE You support the program at your site using the source code that is provided. You can download the periodic upgrades and bug fixes when you need them. 2 FREE Send me suggestions via e-mail which will be categorized and prioritized based on my understanding of the requirements of the user community. 3 $$$$ Contact me about consulting options or a support contract. 1.4 What other documentation packages are available? Please look at this web site for list of C++ documentation systems: http://nz.com/webnz/robert/cpp_site.html#Documentation ================================================================ 2.0 Getting CcDoc CcDoc has been ported to a number of platforms by various folks. I will try to keep track of them here. 2.1 Where can I get CcDoc for Windows NT/98? You can download it from http://www.joelinoff.com/ccdoc . 2.2 Where can I get CcDoc for Solaris? You can download it from http://www.joelinoff.com/ccdoc . 2.3 Where can I get CcDoc for HP? Although I have built CcDoc under HP, the executable is so large, that I can put it on my web site (>8Mb). I recommend that you download the source from http://www.joelinoff.com/ccdoc and compile it locally. 2.4 Where can I get CcDoc for Linux? A number of folks have ported CcDoc to Linux and I have incorporated their suggestions. I am told that it compiles correctly with no changes. I recommend that you download the source from http://www.joelinoff.com/ccdoc and compile it locally. One of my hopes is that I will get enough money from the shareware to get a linux system so that I can build the linux version myself. 2.5 Where can I get CcDoc for AIX? A number of folks have ported CcDoc to AIX and I have incorporated their suggestions. I am told that it compiles correctly with no changes. I recommend that you download the source from http://www.joelinoff.com/ccdoc and compile it locally. 2.6 How do I unpack CcDoc binaries under unix? Download ccdoc_v07a_bin_taz.exe to your local system. % mkdir ccdoc_dev % cd ccdoc_dev % # Download from http://www.joelinoff.com/ccdoc % mv ccdoc_v07a_bin_taz.exe ccdoc_v07a.taz % gunzip ccdoc_v07a.taz % tar xvf 2.7 How do I unpack CcDoc source code under unix? Download ccdoc_v07a_src_taz.exe to your local system. % mkdir ccdoc_dev % cd ccdoc_dev % # Download from http://www.joelinoff.com/ccdoc % mv ccdoc_v07a_src_taz.exe ccdoc_v07a.taz % gunzip ccdoc_v07a.taz % tar xvf % perl tools/ccdoc_pc2unix.pl perl % perl tools/ccdoc_bld.pl In some cases (for example, HP) you might have to edit the tools/ccdoc_pc2unix.pl script to manually remove the ^M characters. 2.8 How do I unpack CcDoc binaries under Windows? Make sure that you have winzip on your system. You can download it from http://www.winzip.com. Download ccdoc_v07a_bin_taz.exe to your local system. % # Download from http://www.joelinoff.com/ccdoc to C:\TEMP % rename ccdoc_v07a_bin_taz.exe ccdoc_v07a.taz % call winzip ccdoc_v07a.taz 2.9 How do I unpack CcDoc source code under Windows? Make sure that you have rktools (or any other tool set that provides tar, gzip, gunzip, ls, mkdir, cd, grep, etc.), tcsh and perl. You can use winzip to unzip the archive but I recommend using the unix type tools because that is how the development environment is set up. Download ccdoc_v07a_src_taz.exe to your local system. % mkdir ccdoc_dev % cd ccdoc_dev % # Download from http://www.joelinoff.com/ccdoc % mv ccdoc_v07a_bin_taz.exe ccdoc_v07a.taz % gunzip ccdoc_v07a.taz % tar xvf % perl tools/ccdoc_bld.pl ================================================================ 3.0 Building CcDoc I develop and build CcDoc on three systems: a Windows 98/NT, HP-UX B.10.20 and Solaris 5.6. 3.1 What tools do you use? I use tcsh as my command shell in all environments. I use standard unix tools (rktools on the PC) for everything except the compiler and make system. I use the Solaris CC 4.2 compiler, the /opt/CC/bin/CC compiler under HP (it has no version switch!) and MS VC++ 5.0 or 6.0. I use standard unix make on all platforms other than windows, I use NMAKE under Windows. I use emacs 20.3 or later as my editor in all environments. I use scripts written in perl 5.003 (or later) on all machines for a common build interface. Those scripts are stored in the tools subdirectory. 3.2 What is the directory structure? The CcDoc directory structure is: ccdoc_dev +--> ccdoc -+---> doc // documentation | | | +---> images // GIF images | | | +---> src // source files | | | +---> test // regression tests | +--> libjdl +---> doc // documentation | | | +---> src // source files | | | +---> test // regression tests +--> tools // porting tools 3.3 How do I build CcDoc? For a unix platform you must strip the ^M characters off of most things. This can be done by first manually removing the ^M characters from the tools/ccdoc_pc2unix.pl tool (this step is not necessary under Solaris or Windows) and then running this tool as follows: % cd ccdoc_dev % perl tools/ccdoc_pc2unix.pl perl After that do this: % cd ccdoc_dev % perl tools/ccdoc_bld.pl I also created the alias: "alias b perl mk.pl" for building individual pieces of the system. To build only the debug version of CcDoc I would do the following: % cd ccdoc_dev/ccdoc/src % b dbg The standard target for building debug versions is "dbg", the standard target for building opt versions is "opt". The standard target for testing is "test". The makefile for each platform is generated automatically and uses the local suffix.mk for customization. 3.4 How do I backup CcDoc? A snapshot backup of CcDoc is created as follows: % cd ccdoc_dev % tools/ccdoc_snp.sh You must have a valid version of tar and gzip in your path for this to work correctly. 3.5 What revision control system do I use? I use RCS 5.x or later under Windows and Unix. ================================================================ 4.0 Running CcDoc, the different phases. CcDoc operates in 3 phases: Phase 1 - Parse the individual source files. Phase 2 - Create the cross reference for all items. Phase 3 - Generate C++. Phase 1 is further broken down into two parts: Phase 1a - Parse the interface files (.h). Phase 1b - Parse the implementation files (.cpp). Phase 1b is new in v0.7a. This phase allows programmers to add comments to the implementation files rather than the interface files. The following sections describe each of these phases in greater detail. 4.1 What does phase 1a do? Phase 1a processing is the parsing phase, this is where all of the input files are converted to an abstract parse tree. This phase assigns language items to specific packages. The parse tree information is written to the CTF file. Shown below is a simple example of phase 1a processing: % rm -f x.ctf % ccdoc -ctf x.ctf -pkg utils utils/*.h % ccdoc -ctf x.ctf -pkg code code/*.h 4.2 What does phase 1b do? Phase 1b processing is an extension of phase 1a process that parses implementation files. The implementation files must be processed after the interface files so that method scope can be determined. Shown below is a simple example of phase 1b processing: % ccdoc -ctf x.ctf -pkg utils utils/*.cpp % ccdoc -ctf x.ctf -pkg code code/*.cpp 4.3 What does phase 2 do? Phase 2 processing is the indexing phase, this is where all nodes in the abstract parse tree are indexed. The index information is written to the CTF file. Shown below is a simple example of phase 2 processing: % ccdoc -ctf x.ctf -index 4.4 What does phase 3 do? Phase 3 processing is the HTML generation phase. During this phase the abstract parse tree and the index information is read and processed to create HTML documentation. Shown below is a simple example of phase 3 processing: % ccdoc -ctf x.ctf \ -v \ -html webdocs/ \ -srcurl http://where.the.source.is/src/ \ -imgurl http://www.joelinoff.com/ccdoc/images/ \ -trailer suffix.html \ -header prefix.html 4.5 What are the CcDoc switches? Switches use by all phases. Switch Description ==================== ============================================== -ctf The name of the CTF (CcDoc Token Format) file. -h On-line help. -log Specify the name of the log file. When the log file is specified messages will be sent to the screen and to the log file simultaneously. It is similar to using the tee command under unix. -[no]v Verbose mode. The default is off. -[no]warn Turn warnings on or off. The default is on. Phase 1 Switches (these work for both subphases) Switch Description ==================== ============================================== -D Define a macro. The macro __ccdoc__ is predefined. Unlike the C++ pre-process, values cannot be assigned to macros. Note that there is no space between the switch and the name. -pkg The name of the package which this contents of this file are associated. Package names can be hierarchical. Hierarchical parts are separated by dots. The following is an example of a hierarchical name: AA.BB.CC. -U Undefine a macro. You can use this switch to undefined __ccdoc__. Phase 2 Switches Switch Description ==================== ============================================== -index Index the contents of the parse tree. Phase 3 Switches Switch Description ==================== ============================================== -bg The background color. The default is white (#FFFFFF). -header The HTML used for the customized prefix. -html 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. -fg The foreground color. The default is black (#000000). -[no]globals Report globally scoped items. Default is on. -[no]gpi Group the pkg index items by type. The default is on. -imageurl -imgurl The URL that describes of the GIF images. It is used a prefix so you must include the directory suffix. -[no]locals Report locally scoped items. Default is on. -[no]macros Report macros. Default is off. -[no]private Report private items. Default is off. -[no]protected Report protected items. Default is on. -[no]public Report public items. Default is on. -root The alternate name for the [ROOT] node. This is the node that always shows up as the root of the package tree. -rooturl The hyperlink for [ROOT]. Setting this allows the ccdoc generated HTML to seamlessly integrate to a higher level document. -sourceurl -srcurl The URL where the source files can be found. If this is specified, hyperlinks are created for Source entries. -trailer The HTML used for the customized trailer. -[no]typedefs Report typedefs. Default is on. 4.6 What environment variables does CcDoc recognize? Variable Description ==================== ============================================== CCDOC_LEXER_DEBUG Turn on lexer debugging. CCDOC_LEXER_RC Specifies an alternate resource file that the user can use to define their own reserved words and keywords. CCDOC_PHASE1B_OFF Turn off phase 1b processing. This will make CcDoc run slightly faster. CCDOC_PHASE3_DEBUG Turn on phase 3 verbose mode. CCDOC_PHASE3_TREE_ANCHORS_OFF Turn off anchors for tree nodes to make visual debugging easier. CCDOC_PARSER_DEBUG Turn on parser debugging. CCDOC_PREP_DEBUG Turn on pre-processor debugging. CCDOC_PREP_SAVE_DEBUG Don't delete the pre-processor temporary files (-PP). CCDOC_STRINGMAP_DEBUG Turn on string map debugging. This is very useful for folks that want to interface directly to the CTF file because it associates the string values with their ids in the parse tree. It is not used by default because it takes up too much disk space. CCDOC_VERBOSE Turn on verbose mode. This the same as using the -v switch on the command line. ================================================================ 5.0 What is the CTF file? The CTF file for CcDoc Token Format file stores the tokenized information about the C++/C entities that CcDoc has parsed. The CTF file is composed of four sections: 1. the version section ('v' record) 2. the string section ('s' record) 3. the node information section ('n' and 'd' records) 4. the cross reference section ('x' record) These sections are always produced in the same order. General Notes: Comments: Comments are delimited by a hash mark (#) and the end of the line. If the hash mark is within a string, it does not begin a comment. If the hash mark is part of a string record it is also not a comment. A sample comment is shown below: # This is a CTF comment Record Format: All CTF records has the same basic format. They start at the beginning of line with a single character identifier. The record fields are separated by colons. The record types are: 'd' - node data record 'n' - node record 's' - string record 'v' - version record 'x' - cross reference record There is one record per line. Debug Mode: In debug mode the string value is printed out as well as its contents. These debug strings always have the following syntax and appear on the same line as the record that contains the referenced string. " %x:%s" ^^ ^ || +--- string value |+------ string length +------- debug marker (space) Debug mode is not efficient because it duplicates the string values. Version Section: The first entry in a CTF file is the version record ('v'). The syntax of the 'v' record is shown below: "v:%s:%s:%s\n" ^ ^ ^ ^ | | | +------- the state of the processing | | +---------- the minor version number (7a) | +------------- the major version number (0) +--------------- the record identifier String Section: To save space, strings are stored in an index at the head of the file. Each entry is called an 's' record (for string record) and has the following syntax: "s:$%x:%x:%s\n" ^ ^ ^ ^ | | | +-------- the string data | | +----------- the string length (hex) | +--------------- the string id form: $ +----------------- the record identifier The first 128 string records are implied, they are the first 128 ASCII characters. Thus, when the value $20 is encountered as a string reference, the system knows that this is a space (' ' == hex 20). Node Section: Nodes are hierarchical entities that describe the C++ entity relationships. Each node record contains the following information. "n:%s:%s:r%x:%x:%x:%x:%x:$%x" ^ ^ ^ ^ ^ ^ ^ ^ ^ | | | | | | | | +-- name id | | | | | | | +----- num d records | | | | | | +-------- lineno | | | | | +----------- offset from parent | | | | +-------------- level | | | +------------------ xref id | | +--------------------- scope name (public, private, ...) | +------------------------ type name +-------------------------- record type indicator In addition, it contains a list of data ('d') nodes whose format is: "d:%c:$%c" ^ ^ ^ | | +----- string id | +-------- type: i-id, r-reserved, k-keyword, ?-unknown +---------- record type The 'd' records are the list of strings associated with the node that comprise the original C++ construct. The scope names are three character strings. The available scope names are: ID Description === =============== ??? unknown scope gbl global scope loc local scope pri private scope pro protected scope pub public scope The type names are three character strings. The available type names are: ID Description ID Description === ================= === ================= asm asm nms namespace cls class nma namespace alias clc constructor prg pragma cld destructor pri private cfw class forward ref pro protected cmb brief comment pub public cmf full comment scf scoped function cmd @ stf scoped template function cmp @pkg str struct cmx @pkgdoc sfw struct forward ref enm enum tmc template class fil file tfw template forward ref frc friend class tmf template function frf friend function typ typedef fct function uni union inc include use using mac macro var variable mai macroinst ??? ?Unknown? The Cross Reference Section: This section keeps a cross reference all node records with the same name. The record format is: "x:%x[:r%x]+:$%x" ^ ^ ^ ^ | | | +---- string id | | +---------- 1 or more reference sub records | +-------------- number of reference sub records +---------------- record id 5.1 How do I merge CTF files? CTF files can be merged with the ctf_merge.pl script provided in release v0.7a. The example below shows how to run this script. % perl ccdoc_merge.pl -i A.ctf -i B.ctf -o C.ctf % ccdoc -index -ctf C.ctf You can have any number of input files (-i) but only one output file (-o). ================================================================ 6.0 Documentation Tips This section presents documentation tips. 6.1 What is the basic comment syntax? CcDoc recognizes comments blocks that occur before C++ constructs. A comment block starts with a '/**' and ends with a '*/'. Each line in the comment block optionally starts with an asterisk '*'. The second line of a comment block and all subsequent lines up to the first blank line contain the summary description of the block. Comments are made up of three basic entities: the brief description, the full description and the directives. The basic format of a comment is shown below: /** * * * * * * . * . * */ A shorthand form of the comments is also available: /** */ The is the information that shows up as the entity descriptor on the summary page. It is separated from the by a blank line. The describes the entity and can include the HTML constructs. The entries start with an @ sign and are the first things (after the optional leading asterisk) on the line. 6.2 What CcDoc directives are available? Directive (Tag) Description =========================== ======================================== /**@#-*/ /**@#+*/ These two tags are used to turn off token parsing in the CcDoc preprocessor. Anything that appears between these two directives is ignored. They are not recursive. These pragmas are useful for ignoring sections of code. For example, many folks use include guards that look something like this: #ifndef _this_include_file #define _this_include_file . . #endif Unfortunately, CcDoc thinks this is of interest (in -macros mode) which generates lots of useless documentation. You can use these directives to tell CcDoc to ignore them as follows: #ifndef _this_include_file /**@#-*/ #define _this_include_file /**@#-*/ . . #endif Another way to do this is to use the __ccdoc_ macro as follows: #ifndef _this_include_file #ifndef __ccdoc__ #define _this_include_file #endif . . #endif The latter method is preferred. @@ Special tag that tells the comment parser to read the rest of the line and convert it to an HTML form that the HTML processor will not try to interpret it. It is useful for documenting the keywords and such in header files. The only translation done on the line is braces are converted to HTML constructs, that is < becomes < and > become >. This is extremely used for embedding code fragments in the comments. @$ Hyperlinks to other classes or methods. This very similar to @see but it can be used anywhere and the @see # mode is not supported. It can be used as follows: /** * This is a brief description, see the * related class * @$ Foo * * This is the full description. *@author Spam *@version $Id: faq.txt,v 1.2 1999/06/14 12:44:25 jdl Exp $ */ @author Specifies the author. For multiple authors the original author should appear first. @exception Specifies that this exception can be thrown by this method. @exceptions Same as @exception. @param Describes a parameter to the method. There is one @param statement for each parameter. @pkg The name of the current package. This comment has a special form: /**@pkg */. It can appear once in a file as a standalone comment to describe the package with which all elements of the file are associated. This directive can be overidden by the -pkg switch on the command line. There is a special package called [NULL] that can be used to say that the contents of the specified file are not part of any package. This special package is used for files that contain only pkg documentation (see the @pkgdoc directive). @pkgdoc The comment form in which this appears is not associated with any C++ element. It is only associated with a package. This is used to document package pages in the hierarchical tree. @return Describes the return value from the method. If there is no return value, do not use the @return. @returns Same as @return. This is the one that I prefer. @see Hyperlinks to other classes or structs. Ccdoc will automatically try to create hyperlink unless the first character is a '<' or a '@'. If the first character is a '<', the parser will assume that you have manually created the hyperlink. If the first character is a '@', the parser will not try to translate the following text. You can also specify methods within a class by separating the method name from the class name using a hash mark '#' or a '::'. For example, if you wish to add a reference to the CJdlString::Compare method you would enter "* @see CJdlString::Compare" in the comment. To reference a method in the local class you must always use the hashmark as follows: "* @see #LocalMethod". To reference another class simply specify the class name as follows: "* @see OtherClass". @source Specify the source file that this class came from. This is a departure from javadoc because the java language guarantees the physical location of a class. You do not need to specify this because CcDoc automatically inserts source information for classes and structs. @version Specifies the version of the class. I usually use the RCS id: $ID:$. 6.3 How do I tell CcDoc to ignore sections of code? There are two ways to tell CcDoc to ignore sections of code. Both are shown in the example below: #ifndef __ccdoc__ // Ignore class A class A { }; #endif /**@#-*/ // Ignore class B class B { }; /**@#+*/ The preferred method is to use the predefined macro __ccdoc__. The second method is more arcane but is maintained for backward compatibility. 6.4 How do I document the root level? The easiest way to document the root level of a system is to create a file called "root.pkg" and insert your documentation. The example below shows what a root.pkg file might look like: // Top level documentation. /**@pkg [NULL]*/ // TOP /** * My stuff root level documentation. * @author FooBar * @version $Id: faq.txt,v 1.2 1999/06/14 12:44:25 jdl Exp $ * @pkgdoc [ROOT] */ This file is then run through ccdoc phase 1 processing as a normal file. 6.5 How do I document a package? In general, to document a package you use the @pkgdoc directive. I generally create a single file called "root.pkg" that contains the documentation for all packages. The example below shows how the ROOT level is redefined (same as 6.1) and package documentation for an intermediate level is also added. // Package documentation. /**@pkg [NULL]*/ // TOP /** * My stuff root level documentation. * @author FooBar * @version $Id: faq.txt,v 1.2 1999/06/14 12:44:25 jdl Exp $ * @pkgdoc [ROOT] */ // TOP.intermediate /** * My stuff intermediate level documentation. * @author FooBar * @version $Id: faq.txt,v 1.2 1999/06/14 12:44:25 jdl Exp $ * @pkgdoc intermediate */ 6.6 How do I embed references to third party tools like RogueWave? The example below shows how to embed documentation for third party tools like Rogue Wave tools.h++. // Package documentation. /**@pkg [NULL]*/ // TOP /** * My stuff root level documentation. * @author FooBar * @version $Id: faq.txt,v 1.2 1999/06/14 12:44:25 jdl Exp $ * @pkgdoc [ROOT] */ // TOP.intermediate /** * My stuff intermediate level documentation. * @author FooBar * @version $Id: faq.txt,v 1.2 1999/06/14 12:44:25 jdl Exp $ * @pkgdoc intermediate */ // TOP.RogueWave /**@Intermediate.RogueWave http://internal/rw/toosug/ug.htm */ 6.7 How do I document a class? The basic comment structure looks like this: /** * * * * * . * . * */ An example comment for a class might look like this: /** * This is the block interface class. | Brief * * The block interface class provides the | Full * the interface that is used by clients when | Full * specializing their classes. | Full * | Full * A client might specialize a class like this: | Full *
                                           | Full
         *@@    class MyBlock : public Block {            | Full
         *@@      .                                       | Full
         *@@      .                                       | Full
         *@@    };                                        | Full
         *
| Full *@author Joe Linoff | Directives *@version $Id: faq.txt,v 1.2 1999/06/14 12:44:25 jdl Exp $ | Directives *@see Bridge | Directives *@see BlockData | Directives */ class Block { }; The directives that are most often used for a class are @author, @version and @see. The *@@ prefix is used to tell CcDoc to substitute the angle brackets correctly. Always use this for code examples. If you don't the HTML parser will get confused by things like: for(int i=0;i<10;i++) { It will think that <10 is the start of an HTML command. When you specify the @@ operator is converts the < to a < so that the HTML comes out properly. The HTML commands 
 and
are used to delimit code. 6.8 How do I document a method? Methods are documented in a similar fashion as shown below: class A { public: /** * Get the type. * * The type of this class is used to determine * whether you can do useful stuff, blah, blah. * Complete information about the types available * are described in * @$ #SetType * . * The example below shows how a client might * use this method. *
           *@@  A::TYPE t = obj->GetType();
           *@@  switch(t) {
           *@@  case A::FOO: ... break;
           *@@  default: ... break;
           *@@  }
           *
* @param detailed If true, return the detailed type. * @returns The object type. * @see #SetType */ TYPE GetType(bool detailed=false) const; }; The most common directives used in method documentation are @param, @returns and @see. The @$ operator tells CcDoc to insert an anchor reference to the specified class or method. Some folks prefer to put the method documentation in the source file. The example below shows how this is done: a.h: class A { public: TYPE GetType() const; }; a.cpp: #include "a.h" /** * Get the type. * * The type of this class is used to determine * whether you can do useful stuff, blah, blah. * Complete information about the types available * are described in * @$ #SetType * @returns The object type. * @see #SetType */ A::TYPE A::GetType() const {...} 6.9 How do I document a variable? Variables can be effectively documented with only the @see and @$ directives. As shown in the example below: class Globals { public: /** * This variable defines the singleton for the * the entire system. *@see CBase */ extern CBase* s_Singleton; }; 6.10 How do I document an enumerated type? You document enumerated types in fashion very similar to variables. You cannot document each type separately so describe all of them in variable comment. The example below shows how this is done. /** * These are the global types recognized by the * system. * * The types are: *
         *    Type      Description
         *    ======    ====================================
         *    INT       32 bit signed integer.
         *    STRING    NULL terminated unsigned char array.
         *    SENTINEL  The end of the list (used for loops).
         *
*/ enum GLOBAL_TYPES { INT, STRING, SENTINEL }; ================================================================ 7.0 Miscellaneous This section presents answers to specific questions. 7.1 How do I embed hyperlinks to CcDoc generated targets? Use the @$ directive that became available in v0.7a. /** * Brief description, take a look at * @$ Class::Method * for more information. */ 7.2 Can I embed my comments in the source file rather than the header file? In CcDoc v0.7a, the program will allow you to define comments in your source file. The brief example below shows how this is done: test.h: class A { public: void DoStuff(); }; test.cpp: /** * CcDoc comment here. */ void A::DoStuff() { } command line: % rm test.ctf % ccdoc -ctf test.ctf test.h % ccdoc -ctf test.ctf test.cpp % ccdoc -ctf test.ctf -index % ccdoc -ctf test.ctf -html ... Note that using this feature causes CcDoc to run more slowly because it has to process many more files. 7.3 Does CcDoc support '//' style comments? Yes. The problem here is that CcDoc expects a multi-line comment form and many code generation tools, such as Rose, generate comments in the single line form. In v0.7a, CcDoc accepts comments of the form: ///** // * Brief description. // * // * Full description. // * @directives. to allow easy integration with code generation tools like the Rose tool. 7.4 How can I embed code fragments in my documentation? You can embed code fragments in your documentation by using a combination of the HTML 
 and
tags and the CcDoc *@@ directive. The example below shows how this is done. /** * Brief comment. * * Full comment with an embedded code * fragment: *
         *@@ int main(int argc,char** argv) {
         *@@   {for(int i=0;i
         */

    If you do not use the @@ directive, the < in the for loop
    will confuse most HTML parsers, they will try to find the
    
        

        
        

        This documentation was generated automatically by the 
        CcDoc v0.7a for Foo v1.0.
        

        Click here
         to submit a bug report or feature request to Owner.
        
        

        % ccdoc -ctf foo.ctf -trailer trailer.html ...