home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / ccdoc07a.zip / doc / faq.txt < prev    next >
Text File  |  1999-06-15  |  48KB  |  1,311 lines
  1. $Id: faq.txt,v 1.2 1999/06/14 12:44:25 jdl Exp $
  2.  
  3. ================================================================
  4. CONTENTS
  5.  
  6.     1.0 What is CcDoc?
  7.     1.1 What is the latest version?
  8.     1.2 How much does it cost?
  9.     1.3 What support options are available?
  10.     1.4 What other documentation packages are available?
  11.     
  12.     2.0 Getting CcDoc
  13.     2.1 Where can I get CcDoc for Windows NT/98?
  14.     2.2 Where can I get CcDoc for Solaris?
  15.     2.3 Where can I get CcDoc for HP?
  16.     2.4 Where can I get CcDoc for Linux?
  17.     2.5 Where can I get CcDoc for AIX?
  18.     2.6 How do I unpack CcDoc binaries under unix?
  19.     2.7 How do I unpack CcDoc source code under unix?
  20.     2.8 How do I unpack CcDoc binaries under Windows?
  21.     2.9 How do I unpack CcDoc source code under Windows?
  22.  
  23.     3.0 Building CcDoc
  24.     3.1 What tools do you use?
  25.     3.2 What is the directory structure?
  26.     3.3 How do I build CcDoc?
  27.     3.4 How do I backup CcDoc?
  28.     3.5 What revision control system do I use?
  29.  
  30.     4.0 Running CcDoc
  31.     4.1 What does phase 1a do?
  32.     4.2 What does phase 1b do?
  33.     4.3 What does phase 2 do?
  34.     4.4 What does phase 3 do?
  35.     4.5 What are the CcDoc switches?
  36.     4.6 What environment variables does CcDoc recognize?
  37.  
  38.     5.0 What is the CTF file?
  39.     5.1 How do I merge CTF files?
  40.     
  41.     6.0 Documentation Tips
  42.     6.1 What is the basic comment syntax?
  43.     6.2 What CcDoc directives are available?
  44.     6.3 How do I tell CcDoc to ignore sections of code?
  45.     6.4 How do I document the root level?
  46.     6.5 How do I document a package?
  47.     6.6 How do I embed references to third party tools like RogueWave?
  48.     6.7 How do I document a class?
  49.     6.8 How do I document a method?
  50.     6.9 How do I document a variable?
  51.     6.10 How do I document an enumerated type?
  52.     
  53.     7.0 Miscellaneous
  54.     7.1 How do I embed hyperlinks to CcDoc generated targets in v0.7 and later?
  55.     7.2 Can I embed my comments in the source file rather than the header file?
  56.     7.3 Does CcDoc support '//' style comments?
  57.     7.4 How can I embed code fragments in my documentation?
  58.     7.5 How do I customize the trailer?
  59.  
  60. ================================================================
  61. 1.0 Introduction
  62.  
  63.     CcDoc tool is a javadoc like tool that automatically
  64.     generates web documentation from C and C++ programs by parsing
  65.     the source file headers (interface definitions). The latest
  66.     versions (v0.7a or later) can also extract documentation from
  67.     from implementation files (.cpp).
  68.  
  69.     It was written because I write code in both Java and C++ and
  70.     wanted a consistent interface for both. I tried very hard to
  71.     stay true to the javadoc syntax and tool flow but, because of
  72.     language differences I was forced to change (or add) a few
  73.     things.
  74.  
  75.     With this tool you do not have to explicitly specify classes,
  76.     methods or variables, the parser figures them out which means
  77.     that it works whether or not you have embedded comments.
  78.  
  79.     This capability allows CcDoc to be run over code with a
  80.     different comment style (or no comment style) to build basic
  81.     web pages that document classes in a set of packages. You can
  82.     add documentation later.
  83.  
  84.     One unique aspect of CcDoc is that it tries to understand
  85.     the program before pre-processing. This allows you to comment
  86.     macro definitions but makes the parsing problem much harder.
  87.  
  88.     If you are interested in being added to my CcDoc mailing
  89.     list, please send me e-mail at jlinoff@ix.netcom.com.
  90.  
  91. 1.1 What is the latest version?
  92.  
  93.     The latest version of CcDoc is v0.7a, released June 1999.
  94.  
  95. 1.2 How much does it cost?
  96.  
  97.     This tool is free software with no express or implied
  98.     warranty. You are free to copy and modify it but you must
  99.     keep the copyright and permissions notices intact.
  100.  
  101.     Starting with v0.8, CcDoc will be provided as shareware for
  102.     $20.00 per copy. The source code will still be provided as 
  103.     part of the release and you can still download the program 
  104.     and try it at no cost.
  105.  
  106.     The only difference is that I am asking that you send
  107.     me a small fee if you find the program useful so that I
  108.     can continue to develop and support it.
  109.  
  110. 1.3 What support options are available?
  111.  
  112.     I have received a number of e-mails asking about what
  113.     support options are available so I will present the range
  114.     of options after I have said a few things.
  115.  
  116.         My intent here is NOT to make money but to
  117.         encourage everyone to use the free internet
  118.         resources
  119.  
  120.         The last option is presented because several
  121.         companies have contacted me about an option
  122.         that they can pay for.
  123.  
  124.     Here they are in my order of preference:
  125.  
  126.         Option  COST  Description
  127.         ======  ====  ===============================
  128.            1    FREE  You support the program at your
  129.                       site using the source code that
  130.                       is provided.
  131.  
  132.                       You can download the periodic
  133.                       upgrades and bug fixes when you
  134.                       need them.
  135.  
  136.            2   FREE   Send me suggestions via e-mail
  137.                       which will be categorized and
  138.                       prioritized based on my
  139.                       understanding of the requirements
  140.                       of the user community.
  141.  
  142.            3   $$$$   Contact me about consulting options
  143.                       or a support contract.
  144.  
  145. 1.4 What other documentation packages are available?
  146.  
  147.     Please look at this web site for list of C++
  148.     documentation systems:
  149.  
  150.       http://nz.com/webnz/robert/cpp_site.html#Documentation
  151.  
  152. ================================================================
  153. 2.0 Getting CcDoc
  154.  
  155.     CcDoc has been ported to a number of platforms by various
  156.     folks. I will try to keep track of them here.
  157.  
  158. 2.1 Where can I get CcDoc for Windows NT/98?
  159.  
  160.     You can download it from http://www.joelinoff.com/ccdoc .
  161.  
  162. 2.2 Where can I get CcDoc for Solaris?
  163.  
  164.     You can download it from http://www.joelinoff.com/ccdoc .
  165.  
  166. 2.3 Where can I get CcDoc for HP?
  167.  
  168.     Although I have built CcDoc under HP, the executable
  169.     is so large, that I can put it on my web site (>8Mb).
  170.  
  171.     I recommend that you download the source from
  172.     http://www.joelinoff.com/ccdoc and compile it
  173.     locally.
  174.  
  175. 2.4 Where can I get CcDoc for Linux?
  176.  
  177.     A number of folks have ported CcDoc to Linux and I
  178.     have incorporated their suggestions. I am told that
  179.     it compiles correctly with no changes.
  180.  
  181.     I recommend that you download the source from
  182.     http://www.joelinoff.com/ccdoc and compile it
  183.     locally.
  184.  
  185.     One of my hopes is that I will get enough money from
  186.     the shareware to get a linux system so that I can 
  187.     build the linux version myself.
  188.  
  189. 2.5 Where can I get CcDoc for AIX?
  190.  
  191.     A number of folks have ported CcDoc to AIX and I
  192.     have incorporated their suggestions. I am told that
  193.     it compiles correctly with no changes.
  194.  
  195.     I recommend that you download the source from
  196.     http://www.joelinoff.com/ccdoc and compile it
  197.     locally.
  198.  
  199. 2.6 How do I unpack CcDoc binaries under unix?
  200.  
  201.     Download ccdoc_v07a_bin_taz.exe to your local system.
  202.  
  203.         % mkdir ccdoc_dev
  204.         % cd ccdoc_dev
  205.         % # Download from http://www.joelinoff.com/ccdoc
  206.         % mv ccdoc_v07a_bin_taz.exe ccdoc_v07a.taz
  207.         % gunzip ccdoc_v07a.taz
  208.         % tar xvf 
  209.  
  210. 2.7 How do I unpack CcDoc source code under unix?
  211.  
  212.     Download ccdoc_v07a_src_taz.exe to your local system.
  213.  
  214.         % mkdir ccdoc_dev
  215.         % cd ccdoc_dev
  216.         % # Download from http://www.joelinoff.com/ccdoc
  217.         % mv ccdoc_v07a_src_taz.exe ccdoc_v07a.taz
  218.         % gunzip ccdoc_v07a.taz
  219.         % tar xvf 
  220.         % perl tools/ccdoc_pc2unix.pl perl
  221.         % perl tools/ccdoc_bld.pl
  222.  
  223.     In some cases (for example, HP) you might have to edit the
  224.     tools/ccdoc_pc2unix.pl script to manually remove the ^M
  225.     characters.
  226.  
  227. 2.8 How do I unpack CcDoc binaries under Windows?
  228.  
  229.     Make sure that you have winzip on your system.
  230.     You can download it from http://www.winzip.com.
  231.  
  232.     Download ccdoc_v07a_bin_taz.exe to your local system.
  233.  
  234.         % # Download from http://www.joelinoff.com/ccdoc to C:\TEMP
  235.         % rename ccdoc_v07a_bin_taz.exe ccdoc_v07a.taz
  236.         % call winzip ccdoc_v07a.taz
  237.  
  238. 2.9 How do I unpack CcDoc source code under Windows?
  239.  
  240.     Make sure that you have rktools (or any other tool
  241.     set that provides tar, gzip, gunzip, ls, mkdir, cd,
  242.     grep, etc.), tcsh and perl.
  243.  
  244.     You can use winzip to unzip the archive but I recommend
  245.     using the unix type tools because that is how the
  246.     development environment is set up.
  247.  
  248.     Download ccdoc_v07a_src_taz.exe to your local system.
  249.  
  250.         % mkdir ccdoc_dev
  251.         % cd ccdoc_dev
  252.         % # Download from http://www.joelinoff.com/ccdoc
  253.         % mv ccdoc_v07a_bin_taz.exe ccdoc_v07a.taz
  254.         % gunzip ccdoc_v07a.taz
  255.         % tar xvf 
  256.         % perl tools/ccdoc_bld.pl
  257.  
  258. ================================================================
  259. 3.0 Building CcDoc
  260.  
  261.     I develop and build CcDoc on three systems: a Windows 98/NT,
  262.     HP-UX B.10.20 and Solaris 5.6.
  263.  
  264. 3.1 What tools do you use?
  265.  
  266.     I use tcsh as my command shell in all environments.
  267.  
  268.     I use standard unix tools (rktools on the PC) for everything
  269.     except the compiler and make system.
  270.  
  271.     I use the Solaris CC 4.2 compiler, the /opt/CC/bin/CC compiler
  272.     under HP (it has no version switch!) and MS VC++ 5.0 or 6.0.
  273.  
  274.     I use standard unix make on all platforms other than windows,
  275.     I use NMAKE under Windows.
  276.  
  277.     I use emacs 20.3 or later as my editor in all environments.
  278.  
  279.     I use scripts written in perl 5.003 (or later) on all machines for
  280.     a common build interface. Those scripts are stored in the tools
  281.     subdirectory.
  282.  
  283. 3.2 What is the directory structure?
  284.  
  285.     The CcDoc directory structure is:
  286.  
  287.        ccdoc_dev +--> ccdoc -+---> doc      // documentation
  288.                  |           |
  289.                  |           +---> images   // GIF images
  290.                  |           |
  291.                  |           +---> src      // source files
  292.                  |           |
  293.                  |           +---> test     // regression tests
  294.                  |           
  295.                  +--> libjdl +---> doc      // documentation
  296.                  |           |
  297.                  |           +---> src      // source files
  298.                  |           |
  299.                  |           +---> test     // regression tests
  300.                  +--> tools                 // porting tools
  301.  
  302. 3.3 How do I build CcDoc?
  303.  
  304.     For a unix platform you must strip the ^M characters off
  305.     of most things. This can be done by first manually removing
  306.     the ^M characters from the tools/ccdoc_pc2unix.pl tool (this step
  307.     is not necessary under Solaris or Windows) and then running
  308.     this tool as follows:
  309.  
  310.     % cd ccdoc_dev
  311.     % perl tools/ccdoc_pc2unix.pl perl
  312.  
  313.     After that do this:
  314.  
  315.     % cd ccdoc_dev
  316.     % perl tools/ccdoc_bld.pl
  317.  
  318.     I also created the alias: "alias b perl mk.pl" for building
  319.     individual pieces of the system.
  320.  
  321.     To build only the debug version of CcDoc I would do the
  322.     following:
  323.  
  324.         % cd ccdoc_dev/ccdoc/src
  325.         % b dbg
  326.  
  327.     The standard target for building debug versions is "dbg",
  328.     the standard target for building opt versions is "opt".
  329.     The standard target for testing is "test".
  330.  
  331.     The makefile for each platform is generated automatically
  332.     and uses the local suffix.mk for customization.
  333.  
  334.  
  335. 3.4 How do I backup CcDoc?
  336.  
  337.     A snapshot backup of CcDoc is created as follows:
  338.  
  339.         % cd ccdoc_dev
  340.         % tools/ccdoc_snp.sh
  341.  
  342.     You must have a valid version of tar and gzip in your
  343.     path for this to work correctly.
  344.  
  345. 3.5 What revision control system do I use?
  346.  
  347.     I use RCS 5.x or later under Windows and Unix.
  348.  
  349. ================================================================
  350. 4.0 Running CcDoc, the different phases.
  351.  
  352.     CcDoc operates in 3 phases:
  353.  
  354.         Phase 1 - Parse the individual source files.
  355.         Phase 2 - Create the cross reference for all items.
  356.         Phase 3 - Generate C++.
  357.  
  358.     Phase 1 is further broken down into two parts:
  359.  
  360.         Phase 1a - Parse the interface files (.h).
  361.         Phase 1b - Parse the implementation files (.cpp).
  362.  
  363.     Phase 1b is new in v0.7a. This phase allows programmers
  364.     to add comments to the implementation files rather than
  365.     the interface files.
  366.  
  367.     The following sections describe each of these phases
  368.     in greater detail.
  369.  
  370. 4.1 What does phase 1a do?
  371.  
  372.     Phase 1a processing is the parsing phase, this is where all of
  373.     the input files are converted to an abstract parse tree. This 
  374.     phase assigns language items to specific packages. The parse 
  375.     tree information is written to the CTF file.
  376.  
  377.     Shown below is a simple example of phase 1a processing:
  378.  
  379.         % rm -f x.ctf
  380.         % ccdoc -ctf x.ctf -pkg utils utils/*.h
  381.         % ccdoc -ctf x.ctf -pkg code  code/*.h
  382.  
  383. 4.2 What does phase 1b do?
  384.  
  385.     Phase 1b processing is an extension of phase 1a process that
  386.     parses implementation files. The implementation files must be
  387.     processed after the interface files so that method scope can
  388.     be determined.
  389.  
  390.     Shown below is a simple example of phase 1b processing:
  391.  
  392.         % ccdoc -ctf x.ctf -pkg utils utils/*.cpp
  393.         % ccdoc -ctf x.ctf -pkg code  code/*.cpp
  394.  
  395. 4.3 What does phase 2 do?
  396.  
  397.     Phase 2 processing is the indexing phase, this is where all 
  398.     nodes in the abstract parse tree are indexed. The index 
  399.     information is written to the CTF file.
  400.  
  401.     Shown below is a simple example of phase 2 processing:
  402.  
  403.         % ccdoc -ctf x.ctf -index
  404.  
  405. 4.4 What does phase 3 do?
  406.  
  407.     Phase 3 processing is the HTML generation phase. During this 
  408.     phase the abstract parse tree and the index information is read 
  409.     and processed to create HTML documentation.
  410.  
  411.     Shown below is a simple example of phase 3 processing:
  412.  
  413.         % ccdoc -ctf x.ctf \
  414.                 -v \
  415.                 -html webdocs/ \
  416.                 -srcurl http://where.the.source.is/src/ \
  417.                 -imgurl http://www.joelinoff.com/ccdoc/images/ \
  418.                 -trailer suffix.html \
  419.                 -header prefix.html
  420.  
  421. 4.5 What are the CcDoc switches?
  422.  
  423.     Switches use by all phases.
  424.  
  425.     Switch                Description
  426.     ====================  ==============================================
  427.     -ctf <file>           The name of the CTF (CcDoc Token Format)
  428.                           file.
  429.  
  430.     -h                    On-line help.
  431.  
  432.     -log <file>           Specify the name of the log file. When the log file
  433.                           is specified messages will be sent to the screen
  434.                           and to the log file simultaneously. It is similar to
  435.                           using the tee command under unix.
  436.  
  437.     -[no]v                Verbose mode. The default is off.
  438.  
  439.     -[no]warn             Turn warnings on or off. The default is on.
  440.  
  441.  
  442.     Phase 1 Switches (these work for both subphases)
  443.  
  444.     Switch                Description
  445.     ====================  ==============================================
  446.     -D<name>              Define a macro. The macro __ccdoc__ is
  447.                           predefined. Unlike the C++ pre-process, values
  448.                           cannot be assigned to macros. Note that there is
  449.                           no space between the switch and the name.
  450.  
  451.     -pkg <name>           The name of the package which this contents of
  452.                           this file are associated. Package names can be
  453.                           hierarchical. Hierarchical parts are separated by
  454.                           dots. The following is an example of a
  455.                           hierarchical name: AA.BB.CC.
  456.  
  457.     -U<name>              Undefine a macro. You can use this switch to
  458.                           undefined __ccdoc__.
  459.  
  460.  
  461.     Phase 2 Switches
  462.  
  463.     Switch                Description
  464.     ====================  ==============================================
  465.     -index                Index the contents of the parse tree.
  466.  
  467.  
  468.     Phase 3 Switches
  469.  
  470.     Switch                Description
  471.     ====================  ==============================================
  472.     -bg <color>           The background color. The default is white
  473.                           (#FFFFFF).
  474.  
  475.     -header <file>        The HTML used for the customized prefix.
  476.  
  477.     -html <prefix>        The HTML path prefix. This is used to designate
  478.                           the path where the HTML files will be stored.
  479.                           The directory suffix must be included if this is a
  480.                           directory path.
  481.  
  482.     -fg <color>           The foreground color. The default is black
  483.                           (#000000).
  484.  
  485.     -[no]globals          Report globally scoped items. Default is on. 
  486.  
  487.     -[no]gpi              Group the pkg index items by type. The default
  488.                           is on. 
  489.  
  490.     -imageurl <URL> 
  491.     -imgurl <URL>         The URL that describes of the GIF images. It is
  492.                           used a prefix so you must include the directory
  493.                           suffix. 
  494.  
  495.     -[no]locals           Report locally scoped items. Default is on. 
  496.  
  497.     -[no]macros           Report macros. Default is off. 
  498.  
  499.     -[no]private          Report private items. Default is off. 
  500.  
  501.     -[no]protected        Report protected items. Default is on. 
  502.  
  503.     -[no]public           Report public items. Default is on. 
  504.  
  505.     -root <name>          The alternate name for the [ROOT] node. This
  506.                           is the node that always shows up as the root of
  507.                           the package tree.
  508.  
  509.     -rooturl <URL>        The hyperlink for [ROOT]. Setting this allows
  510.                           the ccdoc generated HTML to seamlessly
  511.                           integrate to a higher level document.
  512.  
  513.     -sourceurl <URL>
  514.     -srcurl <URL>         The URL where the source files can be found. If
  515.                           this is specified, hyperlinks are created for
  516.                           Source entries.
  517.  
  518.     -trailer <file>       The HTML used for the customized trailer. 
  519.  
  520.     -[no]typedefs         Report typedefs. Default is on. 
  521.  
  522. 4.6 What environment variables does CcDoc recognize?
  523.  
  524.     Variable              Description
  525.     ====================  ==============================================
  526.     CCDOC_LEXER_DEBUG     Turn on lexer debugging.
  527.  
  528.     CCDOC_LEXER_RC        Specifies an alternate resource file that the user
  529.                           can use to define their own reserved words and
  530.                           keywords. 
  531.  
  532.     CCDOC_PHASE1B_OFF     Turn off phase 1b processing. This will make CcDoc
  533.                           run slightly faster.
  534.  
  535.     CCDOC_PHASE3_DEBUG    Turn on phase 3 verbose mode. 
  536.  
  537.     CCDOC_PHASE3_TREE_ANCHORS_OFF
  538.                           Turn off anchors for tree nodes to make visual
  539.                           debugging easier. 
  540.  
  541.     CCDOC_PARSER_DEBUG    Turn on parser debugging. 
  542.  
  543.     CCDOC_PREP_DEBUG      Turn on pre-processor debugging. 
  544.  
  545.     CCDOC_PREP_SAVE_DEBUG Don't delete the pre-processor temporary files
  546.                           (<file>-PP).
  547.  
  548.     CCDOC_STRINGMAP_DEBUG Turn on string map debugging. This is very
  549.                           useful for folks that want to interface directly to
  550.                           the CTF file because it associates the string
  551.                           values with their ids in the parse tree. It is not
  552.                           used by default because it takes up too much
  553.                           disk space. 
  554.  
  555.     CCDOC_VERBOSE         Turn on verbose mode. This the same as using
  556.                           the -v switch on the command line. 
  557.  
  558. ================================================================
  559. 5.0 What is the CTF file?
  560.  
  561.     The CTF file for CcDoc Token Format file stores the tokenized
  562.     information about the C++/C entities that CcDoc has parsed.
  563.  
  564.     The CTF file is composed of four sections:
  565.  
  566.         1. the version section ('v' record)
  567.         2. the string section ('s' record)
  568.         3. the node information section ('n' and 'd' records)
  569.         4. the cross reference section ('x' record)
  570.  
  571.     These sections are always produced in the same order.
  572.  
  573.     General Notes:
  574.  
  575.         Comments:
  576.  
  577.             Comments are delimited by a hash mark (#) and the end of
  578.             the line. If the hash mark is within a string, it does
  579.             not begin a comment. If the hash mark is part of a string
  580.             record it is also not a comment.
  581.  
  582.             A sample comment is shown below:
  583.  
  584.                 # This is a CTF comment
  585.  
  586.         Record Format:
  587.  
  588.             All CTF records has the same basic format. They start
  589.             at the beginning of line with a single character
  590.             identifier. The record fields are separated by colons.
  591.  
  592.             The record types are:
  593.  
  594.                 'd' - node data record
  595.                 'n' - node record
  596.                 's' - string record
  597.                 'v' - version record
  598.                 'x' - cross reference record
  599.  
  600.             There is one record per line.
  601.  
  602.         Debug Mode:
  603.  
  604.             In debug mode the string value is printed out as well as
  605.             its contents. These debug strings always have the
  606.             following syntax and appear on the same line as
  607.             the record that contains the referenced string.
  608.         
  609.                 " %x:%s"
  610.                  ^^  ^
  611.                  ||  +--- string value
  612.                  |+------ string length
  613.                  +------- debug marker (space)
  614.  
  615.             Debug mode is not efficient because it duplicates
  616.             the string values.
  617.  
  618.     Version Section:
  619.  
  620.         The first entry in a CTF file is the version record ('v').
  621.  
  622.         The syntax of the 'v' record is shown below:
  623.  
  624.             "v:%s:%s:%s\n"
  625.              ^ ^  ^  ^
  626.              | |  |  +------- the state of the processing
  627.              | |  +---------- the minor version number (7a)
  628.              | +------------- the major version number (0)
  629.              +--------------- the record identifier
  630.  
  631.     String Section:
  632.  
  633.         To save space, strings are stored in an index at the head
  634.         of the file.
  635.  
  636.         Each entry is called an 's' record (for string
  637.         record) and has the following syntax:
  638.  
  639.             "s:$%x:%x:%s\n"
  640.              ^ ^   ^  ^
  641.              | |   |  +-------- the string data
  642.              | |   +----------- the string length (hex)
  643.              | +--------------- the string id form: $<hex num>
  644.              +----------------- the record identifier
  645.     
  646.         The first 128 string records are implied, they are the
  647.         first 128 ASCII characters. Thus, when the value $20 is
  648.         encountered as a string reference, the system knows that
  649.         this is a space (' ' == hex 20).
  650.  
  651.     Node Section:
  652.  
  653.         Nodes are hierarchical entities that describe the
  654.         C++ entity relationships.
  655.     
  656.         Each node record contains the following information.
  657.     
  658.             "n:%s:%s:r%x:%x:%x:%x:%x:$%x"
  659.              ^ ^  ^  ^   ^  ^  ^  ^  ^
  660.              | |  |  |   |  |  |  |  +-- name id
  661.              | |  |  |   |  |  |  +----- num d records
  662.              | |  |  |   |  |  +-------- lineno
  663.              | |  |  |   |  +----------- offset from parent
  664.              | |  |  |   +-------------- level
  665.              | |  |  +------------------ xref id
  666.              | |  +--------------------- scope name (public, private, ...)
  667.              | +------------------------ type name
  668.              +-------------------------- record type indicator
  669.     
  670.         In addition, it contains a list of data ('d') nodes whose
  671.         format is:
  672.     
  673.             "d:%c:$%c"
  674.              ^ ^  ^
  675.              | |  +----- string id
  676.              | +-------- type: i-id, r-reserved, k-keyword, ?-unknown
  677.              +---------- record type
  678.     
  679.         The 'd' records are the list of strings associated with
  680.         the node that comprise the original C++ construct.
  681.  
  682.         The scope names are three character strings. The available
  683.         scope names are:
  684.  
  685.             ID   Description
  686.             ===  ===============
  687.             ???  unknown scope
  688.             gbl  global scope
  689.             loc  local scope
  690.             pri  private scope
  691.             pro  protected scope
  692.             pub  public scope
  693.  
  694.         The type names are three character strings. The available
  695.         type names are:
  696.     
  697.             ID   Description         ID   Description
  698.             ===  =================   ===  =================
  699.             asm  asm                 nms  namespace
  700.             cls  class               nma  namespace alias
  701.             clc  constructor         prg  pragma
  702.             cld  destructor          pri  private
  703.             cfw  class forward ref   pro  protected
  704.             cmb  brief comment       pub  public
  705.             cmf  full comment        scf  scoped function
  706.             cmd  @<directive>        stf  scoped template function
  707.             cmp  @pkg                str  struct
  708.             cmx  @pkgdoc             sfw  struct forward ref
  709.             enm  enum                tmc  template class
  710.             fil  file                tfw  template forward ref
  711.             frc  friend class        tmf  template function
  712.             frf  friend function     typ  typedef
  713.             fct  function            uni  union
  714.             inc  include             use  using 
  715.             mac  macro               var  variable
  716.             mai  macroinst           ???  ?Unknown?
  717.  
  718.     The Cross Reference Section:
  719.     
  720.         This section keeps a cross reference all node records
  721.         with the same name.
  722.  
  723.         The record format is:
  724.  
  725.             "x:%x[:r%x]+:$%x"
  726.              ^ ^   ^     ^
  727.              | |   |     +---- string id
  728.              | |   +---------- 1 or more reference sub records
  729.              | +-------------- number of reference sub records
  730.              +---------------- record id
  731.  
  732. 5.1 How do I merge CTF files?
  733.  
  734.     CTF files can be merged with the ctf_merge.pl script
  735.     provided in release v0.7a. The example below shows
  736.     how to run this script.
  737.  
  738.         % perl ccdoc_merge.pl -i A.ctf -i B.ctf -o C.ctf
  739.         % ccdoc -index -ctf C.ctf
  740.  
  741.     You can have any number of input files (-i) but only
  742.     one output file (-o).
  743.  
  744. ================================================================
  745. 6.0 Documentation Tips
  746.  
  747.     This section presents documentation tips.
  748.  
  749. 6.1 What is the basic comment syntax?
  750.  
  751.     CcDoc recognizes comments blocks that occur before C++ constructs.
  752.  
  753.     A comment block starts with a '/**' and ends with a '*/'. Each
  754.     line in the comment block optionally starts with an asterisk '*'.
  755.     The second line of a comment block and all subsequent lines up 
  756.     to the first blank line contain the summary description of the
  757.     block.
  758.  
  759.     Comments are made up of three basic entities: the brief description,
  760.     the full description and the directives. The basic format of a 
  761.     comment is shown below:
  762.  
  763.         /**
  764.          * <brief description>
  765.          *
  766.          * <full description>
  767.          * <directive>
  768.          * <directive>
  769.          * .
  770.          * .
  771.          * <directive>
  772.          */
  773.  
  774.     A shorthand form of the comments is also available:
  775.  
  776.         /** <brief description> */
  777.  
  778.     The <brief description> is the information that shows up as the 
  779.     entity descriptor on the summary page. It is separated from the 
  780.     <full description> by a blank line.
  781.  
  782.     The <full description> describes the entity and can include the 
  783.     HTML constructs.
  784.  
  785.     The <directive> entries start with an @ sign and are the first
  786.     things (after the optional leading asterisk) on the line.
  787.  
  788. 6.2 What CcDoc directives are available?
  789.  
  790.     Directive (Tag)              Description
  791.     ===========================  ========================================
  792.     /**@#-*/
  793.     /**@#+*/                     These two tags are used to turn off token
  794.                                  parsing in the CcDoc preprocessor. Anything
  795.                                  that appears between these two directives 
  796.                                  is ignored. They are not recursive.
  797.  
  798.                                  These pragmas are useful for ignoring sections
  799.                                  of code. For example, many folks use include
  800.                                  guards that look something like this:
  801.  
  802.                                     #ifndef _this_include_file
  803.                                     #define _this_include_file
  804.                                     .
  805.                                     .
  806.                                     #endif
  807.  
  808.                                  Unfortunately, CcDoc thinks this is of interest 
  809.                                  (in -macros mode) which generates lots of 
  810.                                  useless documentation.
  811.  
  812.                                  You can use these directives to tell CcDoc to 
  813.                                  ignore them as follows:
  814.  
  815.                                      #ifndef _this_include_file
  816.                                      /**@#-*/
  817.                                      #define _this_include_file
  818.                                      /**@#-*/
  819.                                      .
  820.                                      .
  821.                                      #endif
  822.  
  823.                                  Another way to do this is to use the __ccdoc_
  824.                                  macro as follows:
  825.  
  826.                                      #ifndef _this_include_file
  827.                                      #ifndef __ccdoc__
  828.                                      #define _this_include_file
  829.                                      #endif
  830.                                      .
  831.                                      .
  832.                                      #endif
  833.  
  834.                                  The latter method is preferred.
  835.  
  836.     @@                           Special tag that tells the comment parser 
  837.                                  to read the rest of the line and convert 
  838.                                  it to an HTML form that the HTML processor
  839.                                  will not try to interpret it.
  840.  
  841.                                  It is useful for documenting the keywords
  842.                                  and such in header files. The only translation
  843.                                  done on the line is braces are converted
  844.                                  to HTML constructs, that is < becomes <
  845.                                  and > become >.
  846.  
  847.                                  This is extremely used for embedding code
  848.                                  fragments in the comments. 
  849.  
  850.     @$ <name>                    Hyperlinks to other classes or methods. This
  851.                                  very similar to @see but it can be used anywhere
  852.                                  and the @see # mode is not supported.
  853.  
  854.                                  It can be used as follows:
  855.  
  856.                                      /**
  857.                                       * This is a brief description, see the
  858.                                       * related class
  859.                                       * @$ Foo
  860.                                       *
  861.                                       * This is the full description.
  862.                                       *@author Spam
  863.                                       *@version $Id: faq.txt,v 1.2 1999/06/14 12:44:25 jdl Exp $
  864.                                       */
  865.  
  866.     @author <name>               Specifies the author. For multiple authors 
  867.                                  the original author should appear first. 
  868.  
  869.     @exception <name>            Specifies that this exception can be thrown 
  870.                                  by this method.
  871.  
  872.     @exceptions <name>           Same as @exception. 
  873.  
  874.     @param <name> <description>  Describes a parameter to the method. There
  875.                                  is one @param statement for each parameter. 
  876.  
  877.     @pkg <name>                  The name of the current package. This comment
  878.                                  has a special form: /**@pkg <name>*/. It can
  879.                                  appear once in a file as a standalone comment
  880.                                  to describe the package with which all elements
  881.                                  of the file are associated. This directive can
  882.                                  be overidden by the -pkg switch on the command
  883.                                  line.
  884.  
  885.                                  There is a special package called [NULL] that
  886.                                  can be used to say that the contents of the
  887.                                  specified file are not part of any package. This
  888.                                  special package is used for files that contain 
  889.                                  only pkg documentation (see the @pkgdoc directive).
  890.  
  891.     @pkgdoc <name>               The comment form in which this appears is not 
  892.                                  associated with any C++ element. It is only 
  893.                                  associated with a package. This is used to 
  894.                                  document package pages in the hierarchical tree.
  895.  
  896.     @return <description>        Describes the return value from the method. If 
  897.                                  there is no return value, do not use the @return. 
  898.  
  899.     @returns <description>       Same as @return. This is the one that I prefer. 
  900.  
  901.     @see <name>                  Hyperlinks to other classes or structs. Ccdoc will 
  902.                                  automatically try to create hyperlink unless the 
  903.                                  first character is a '<' or a '@'. 
  904.  
  905.                                  If the first character is a '<', the parser will 
  906.                                  assume that you have manually created the hyperlink.
  907.  
  908.                                  If the first character is a '@', the parser will
  909.                                  not try to translate the following text. 
  910.  
  911.                                  You can also specify methods within a class by 
  912.                                  separating the method name from the class name
  913.                                  using a hash mark '#' or a '::'.
  914.  
  915.                                  For example, if you wish to add a reference to
  916.                                  the CJdlString::Compare method you would enter
  917.  
  918.                                      "* @see CJdlString::Compare"
  919.  
  920.                                  in the comment.
  921.  
  922.                                  To reference a method in the local class you must
  923.                                  always use the hashmark as follows:
  924.  
  925.                                      "* @see #LocalMethod". 
  926.  
  927.                                  To reference another class simply specify the 
  928.                                  class name as follows:
  929.  
  930.                                      "* @see OtherClass". 
  931.  
  932.     @source <file>               Specify the source file that this class came from.
  933.                                  This is a departure from javadoc because the java
  934.                                  language guarantees the physical location of a class. 
  935.  
  936.                                  You do not need to specify this because CcDoc 
  937.                                  automatically inserts source information
  938.                                  for classes and structs.
  939.  
  940.     @version <id>                Specifies the version of the class. I usually use the 
  941.                                  RCS id: $ID:$. 
  942.  
  943. 6.3 How do I tell CcDoc to ignore sections of code?
  944.  
  945.     There are two ways to tell CcDoc to ignore sections of
  946.     code. Both are shown in the example below:
  947.  
  948.     #ifndef __ccdoc__
  949.     // Ignore class A
  950.     class A {
  951.     };
  952.     #endif
  953.  
  954.     /**@#-*/
  955.     // Ignore class B
  956.     class B {
  957.     };
  958.     /**@#+*/
  959.  
  960.     The preferred method is to use the predefined 
  961.     macro __ccdoc__. The second method is more
  962.     arcane but is maintained for backward compatibility.
  963.  
  964. 6.4 How do I document the root level?
  965.  
  966.     The easiest way to document the root level of
  967.     a system is to create a file called "root.pkg"
  968.     and insert your documentation.
  969.  
  970.     The example below shows what a root.pkg file
  971.     might look like:
  972.  
  973.         // Top level documentation.
  974.         /**@pkg [NULL]*/
  975.  
  976.         // TOP
  977.         /**
  978.          * My stuff root level documentation.
  979.          * @author FooBar
  980.          * @version $Id: faq.txt,v 1.2 1999/06/14 12:44:25 jdl Exp $
  981.          * @pkgdoc [ROOT]
  982.          */
  983.  
  984.     This file is then run through ccdoc phase 1 processing
  985.     as a normal file.
  986.  
  987. 6.5 How do I document a package?
  988.  
  989.     In general, to document a package you use the @pkgdoc
  990.     directive. I generally create a single file called "root.pkg"
  991.     that contains the documentation for all packages.
  992.  
  993.     The example below shows how the ROOT level is redefined
  994.     (same as 6.1) and package documentation for an intermediate
  995.     level is also added.
  996.  
  997.         // Package documentation.
  998.         /**@pkg [NULL]*/
  999.  
  1000.         // TOP
  1001.         /**
  1002.          * My stuff root level documentation.
  1003.          * @author FooBar
  1004.          * @version $Id: faq.txt,v 1.2 1999/06/14 12:44:25 jdl Exp $
  1005.          * @pkgdoc [ROOT]
  1006.          */
  1007.  
  1008.         // TOP.intermediate
  1009.         /**
  1010.          * My stuff intermediate level documentation.
  1011.          * @author FooBar
  1012.          * @version $Id: faq.txt,v 1.2 1999/06/14 12:44:25 jdl Exp $
  1013.          * @pkgdoc intermediate
  1014.          */
  1015.  
  1016. 6.6 How do I embed references to third party tools like RogueWave?
  1017.  
  1018.     The example below shows how to embed documentation for
  1019.     third party tools like Rogue Wave tools.h++.
  1020.  
  1021.         // Package documentation.
  1022.         /**@pkg [NULL]*/
  1023.  
  1024.         // TOP
  1025.         /**
  1026.          * My stuff root level documentation.
  1027.          * @author FooBar
  1028.          * @version $Id: faq.txt,v 1.2 1999/06/14 12:44:25 jdl Exp $
  1029.          * @pkgdoc [ROOT]
  1030.          */
  1031.  
  1032.         // TOP.intermediate
  1033.         /**
  1034.          * My stuff intermediate level documentation.
  1035.          * @author FooBar
  1036.          * @version $Id: faq.txt,v 1.2 1999/06/14 12:44:25 jdl Exp $
  1037.          * @pkgdoc intermediate
  1038.          */
  1039.  
  1040.         // TOP.RogueWave
  1041.         /**@Intermediate.RogueWave http://internal/rw/toosug/ug.htm */
  1042.  
  1043. 6.7 How do I document a class?
  1044.  
  1045.     The basic comment structure looks like this:
  1046.  
  1047.         /**
  1048.          * <brief>
  1049.          *
  1050.          * <full>
  1051.          * <directive>
  1052.          * .
  1053.          * .
  1054.          * <directive>
  1055.          */
  1056.     
  1057.     An example comment for a class might look like this:
  1058.  
  1059.         /**
  1060.          * This is the block interface class.             | Brief
  1061.          *
  1062.          * The block interface class provides the         | Full
  1063.          * the interface that is used by clients when     | Full
  1064.          * specializing their classes.                    | Full
  1065.          *                                                | Full
  1066.          * A client might specialize a class like this:   | Full
  1067.          *<pre>                                           | Full
  1068.          *@@    class MyBlock : public Block {            | Full
  1069.          *@@      .                                       | Full
  1070.          *@@      .                                       | Full
  1071.          *@@    };                                        | Full
  1072.          *</pre>                                          | Full
  1073.          *@author Joe Linoff                              | Directives
  1074.          *@version $Id: faq.txt,v 1.2 1999/06/14 12:44:25 jdl Exp $                                  | Directives
  1075.          *@see Bridge                                     | Directives
  1076.          *@see BlockData                                  | Directives
  1077.          */
  1078.         class Block {
  1079.         };
  1080.  
  1081.     The directives that are most often used for a class are @author,
  1082.     @version and @see.
  1083.  
  1084.     The *@@ prefix is used to tell CcDoc to substitute the
  1085.     angle brackets correctly. Always use this for code
  1086.     examples. If you don't the HTML parser will get confused
  1087.     by things like:
  1088.  
  1089.        for(int i=0;i<10;i++) {
  1090.  
  1091.     It will think that <10 is the start of an HTML command.
  1092.     When you specify the @@ operator is converts the < to
  1093.     a < so that the HTML comes out properly.
  1094.  
  1095.     The HTML commands <pre> and </pre> are used to delimit
  1096.     code.
  1097.  
  1098. 6.8 How do I document a method?
  1099.  
  1100.     Methods are documented in a similar fashion as shown below:
  1101.  
  1102.         class A {
  1103.         public:
  1104.           /**
  1105.            * Get the type.
  1106.            *
  1107.            * The type of this class is used to determine
  1108.            * whether you can do useful stuff, blah, blah.
  1109.            * Complete information about the types available
  1110.            * are described in
  1111.            * @$ #SetType
  1112.            * .
  1113.            * The example below shows how a client might
  1114.            * use this method.
  1115.            *<pre>
  1116.            *@@  A::TYPE t = obj->GetType();
  1117.            *@@  switch(t) {
  1118.            *@@  case A::FOO: ... break;
  1119.            *@@  default: ... break;
  1120.            *@@  }
  1121.            *</pre>
  1122.            * @param detailed If true, return the detailed type.
  1123.            * @returns The object type.
  1124.            * @see #SetType
  1125.            */
  1126.           TYPE GetType(bool detailed=false) const;
  1127.         };
  1128.  
  1129.     The most common directives used in method documentation
  1130.     are @param, @returns and @see.
  1131.  
  1132.     The @$ operator tells CcDoc to insert an anchor reference
  1133.     to the specified class or method.
  1134.  
  1135.     Some folks prefer to put the method documentation in the
  1136.     source file. The example below shows how this is done:
  1137.  
  1138.         a.h:
  1139.             class A {
  1140.             public:
  1141.               TYPE GetType() const;
  1142.             };
  1143.  
  1144.         a.cpp:
  1145.             #include "a.h"
  1146.  
  1147.             /**
  1148.              * Get the type.
  1149.              *
  1150.              * The type of this class is used to determine
  1151.              * whether you can do useful stuff, blah, blah.
  1152.              * Complete information about the types available
  1153.              * are described in
  1154.              * @$ #SetType
  1155.              * @returns The object type.
  1156.              * @see #SetType
  1157.              */
  1158.             A::TYPE A::GetType() const {...}
  1159.  
  1160. 6.9 How do I document a variable?
  1161.  
  1162.     Variables can be effectively documented with only the @see
  1163.     and @$ directives. As shown in the example below:
  1164.  
  1165.         class Globals {
  1166.         public:
  1167.           /**
  1168.            * This variable defines the singleton for the
  1169.            * the entire system.
  1170.            *@see CBase
  1171.            */
  1172.           extern CBase* s_Singleton;
  1173.         };
  1174.  
  1175. 6.10 How do I document an enumerated type?
  1176.  
  1177.     You document enumerated types in fashion very similar
  1178.     to variables. You cannot document each type separately
  1179.     so describe all of them in variable comment.
  1180.  
  1181.     The example below shows how this is done.
  1182.  
  1183.         /**
  1184.          * These are the global types recognized by the
  1185.          * system.
  1186.          *
  1187.          * The types are:
  1188.          *<pre>
  1189.          *    Type      Description
  1190.          *    ======    ====================================
  1191.          *    INT       32 bit signed integer.
  1192.          *    STRING    NULL terminated unsigned char array.
  1193.          *    SENTINEL  The end of the list (used for loops).
  1194.          *</pre>
  1195.          */
  1196.         enum GLOBAL_TYPES {
  1197.           INT,
  1198.           STRING,
  1199.           SENTINEL
  1200.         };
  1201.  
  1202. ================================================================
  1203. 7.0 Miscellaneous
  1204.  
  1205.     This section presents answers to specific questions.
  1206.  
  1207. 7.1 How do I embed hyperlinks to CcDoc generated targets?
  1208.  
  1209.     Use the @$ directive that became available in v0.7a.
  1210.  
  1211.         /**
  1212.           * Brief description, take a look at
  1213.           * @$ Class::Method
  1214.           * for more information.
  1215.           */
  1216.  
  1217. 7.2 Can I embed my comments in the source file rather than the header file?
  1218.  
  1219.     In CcDoc v0.7a, the program will allow you
  1220.     to define comments in your source file. The
  1221.     brief example below shows how this is done:
  1222.  
  1223.         test.h:
  1224.             class A {
  1225.             public:
  1226.               void DoStuff();
  1227.             };
  1228.  
  1229.         test.cpp:
  1230.             /**
  1231.              * CcDoc comment here.
  1232.              */
  1233.             void A::DoStuff() {
  1234.             }
  1235.  
  1236.         command line:
  1237.             % rm test.ctf
  1238.             % ccdoc -ctf test.ctf test.h
  1239.             % ccdoc -ctf test.ctf test.cpp
  1240.             % ccdoc -ctf test.ctf -index
  1241.             % ccdoc -ctf test.ctf -html ...
  1242.     Note that using this feature causes CcDoc to run
  1243.     more slowly because it has to process many more
  1244.     files.
  1245.  
  1246. 7.3 Does CcDoc support '//' style comments?
  1247.  
  1248.     Yes. 
  1249.  
  1250.     The problem here is that CcDoc expects a multi-line
  1251.     comment form and many code generation tools, such as
  1252.     Rose, generate comments in the single line form.
  1253.  
  1254.     In v0.7a, CcDoc accepts comments of the form:
  1255.  
  1256.         ///**
  1257.         // * Brief description.
  1258.         // *
  1259.         // * Full description. 
  1260.         // * @directives.
  1261.  
  1262.     to allow easy integration with code generation tools like
  1263.     the Rose tool.
  1264.  
  1265. 7.4 How can I embed code fragments in my documentation?
  1266.  
  1267.     You can embed code fragments in your documentation by
  1268.     using a combination of the HTML <pre> and </pre> tags
  1269.     and the CcDoc *@@ directive. The example below shows how
  1270.     this is done.
  1271.  
  1272.         /**
  1273.          * Brief comment.
  1274.          *
  1275.          * Full comment with an embedded code
  1276.          * fragment:
  1277.          *<pre>
  1278.          *@@ int main(int argc,char** argv) {
  1279.          *@@   {for(int i=0;i<argc;i++) {
  1280.          *@@     print("argv[%d] = '%s'\n",i,argv[i]);
  1281.          *@@   }}
  1282.          *@@   return 0;
  1283.          *@@ }
  1284.          *</pre>
  1285.          */
  1286.  
  1287.     If you do not use the @@ directive, the < in the for loop
  1288.     will confuse most HTML parsers, they will try to find the
  1289.     <argc tag.
  1290.  
  1291. 7.5 How do I customize the trailer?
  1292.  
  1293.     Create a trailer file and reference it using the
  1294.     -trailer switch in phase 3. The example below
  1295.     shows how to create a trailer file called trailer.html
  1296.     for a product called Foo.
  1297.  
  1298.         % cat trailer.html
  1299.         <!-- Custom trailer for Foo v1.0 -->
  1300.         <center>
  1301.         <font size="-1">
  1302.         <p>
  1303.         This documentation was generated automatically by the 
  1304.         CcDoc v0.7a for Foo v1.0.
  1305.         <br>
  1306.         Click <a href=\"mailto:Owner\">here</a>
  1307.          to submit a bug report or feature request to Owner.
  1308.         </font>
  1309.         </center>
  1310.         % ccdoc -ctf foo.ctf -trailer trailer.html ...
  1311.