1ccdoc v08r41 2004/09/29 bin_dbg_msvc_MSWin32-x86-multi-thread-4.0 2ccdoc help 2004/09/29 3Copyright (C) 1998-2004 by Joe Linoff. 4 5For more information see http://ccdoc.sourceforge.net or 6http://www.joelinoff.com/ccdoc. 7 8 Table of Contents 9 10 Introduction ...................................... 1 11 Phase Independent Switches ........................ 2 12 Parse Phase ....................................... 3 13 Index Phase ....................................... 4 14 Output Phase ...................................... 5 15 Running the Program ............................... 6 16 Comment Directives ................................ 7 17 Comment Format .................................... 8 18 Package Help ...................................... 9 19 201 Introduction 21 22 This program analyzes C++ declarations and produces HTML 23 documentation. 24 25 It has three basic operating phases: Parse, Index and Output. Each 26 phase is described in more detail below. 27 28 Phase Description 29 ====== ========================================== 30 Parse Parse C++ declarations and ccdoc comments. 31 Index Generate cross references. 32 Output Generate HTML output. 33 34 Phases are defined by the switches that are used on the command 35 line. Multiple phases can be specified in a single run. The phases 36 are described in the following sections. Each section describes the 37 phase specific switches and presents some usage examples. 38 39 After the phases have been discussed there is a section on flow 40 which describes different usage models and, following that, there is 41 a summary of the ccdoc comment directives. 42 432 Phase Independent Switches 44 45 This section presents the switches that can be used in any phase or, 46 as is the case with -h, no phase. 47 48 Switch Description 49 ============ ====================================================== 50 -args Dump the command line arguments. This is enabled 51 automatically in verbose (-v) mode. 52 53 -cid Deprecated. Same as -verbose. 54 55 -ctf <file> Deprecated. Same as -db. 56 57 -db <file> The name of the ccdoc database. 58 59 -h,-help Displays the extensive on-line help and exits. 60 The on-line covers the different program phases, the 61 comment directives and the program switches. 62 63 -log <file> All information output by the program is also sent 64 to the specified log file. Multiple log files can be 65 specified. By default all output is sent to cout. 66 67 -nocout Turn off output to cout. This is used to test the 68 help output without displaying anything to the 69 console. 70 71 -putenv <env> Set an environment variable from the command line. 72 This is useful for setting up regression tests in 73 scripts on various platforms. 74 75 -[no]v Turn verbose mode on or off. The default is off. 76 77 -version Report the program version. The version contains the 78 program name, the version, the revision, the release 79 date and the compilation id. Here is an example of 80 what -version reports: 81 % ccdoc -version 82 ccdoc v08r41 2004/09/29 bin_opt_msvc_MSWin32-multi-thread-4.0 83 84 -[no]vf Turn db verbose format mode on or off. The default is 85 on because it speeds up the writing significantly and 86 is only slightly larger. This switch enables verbose 87 mode in the database file to make things easier to 88 read for debugging. 89 90 -[no]warn Turn warnings on or off. The default is on. 91 ============ ====================================================== 92 93 Here is an example that shows how to output this help information to 94 a log file: 95 96 % ccdoc -log help.log -h 97 983 Parse Phase 99 100 During the parse phase C++ files are parsed to find declarations and 101 ccdoc comments. These entities are tokenized and stored into the 102 database specified by the -db switch. The parse phase is specified 103 by the -pkg switch or the presence of source files on the command 104 line. 105 106 When new files are parsed, the indexing information from previous 107 runs is lost. 108 109 Switch Description 110 ================== ================================================== 111 -[no]cdsm Turn on or off the creation of default special 112 members for classes. Specifically this tells ccdoc 113 to create (or not create) entries for default 114 constructors, copy constructors, destructors and 115 copy operators if they were not explicitly defined 116 in the class. The default is -cdsm. 117 118 -db <file> The name of the ccdoc database. 119 120 -D<name>[=<value>] Define a macro and, optionally, define its value. 121 122 -[no]doxygen Enable limited doxygen compatibility mode. 123 The default is -doxygen. 124 This switch specifies that @file 125 blocks are ignored. 126 127 Some other doxygen compatible syntax is already 128 supported whether this switch is specified or 129 not, namely: the @endlink directive, the single 130 line suffix comment forms (//!< and ///<) and 131 the multiple line suffix comment forms (/*!< and 132 /**<). 133 134 This allows users more flexibility in converting 135 between doxygen and ccdoc. 136 137 -files <list> Designates a file that contains the list of files 138 to parse. 139 140 -[no]jdsds Enable javadoc short description syntax. This 141 causes ccdoc to conform to the javadoc 142 specification for processing short descriptions. 143 144 This is the new default behavior as of r24. 145 146 A javadoc short description is terminated by a 147 period followed by a space, tab, newline or tag 148 (directive). 149 150 If -nojdsds is specified, the old-style ccdoc 151 short description handling is enabled. That is, 152 short descriptions are terminated by a blank 153 line. 154 155 -pkg <name> Define the package name for the entities in the 156 source files. If no package is specified a 157 default name is used or the @pkg <name> 158 directive in the ccdoc comment is used. Children 159 (like class methods) inherit the package from 160 their parent. 161 162 -[no]tcms Turn on or off the processing of template class 163 methods that are defined outside of the class 164 declaration. 165 166 -U<name> Undefine a macro. 167 ================== ================================================== 168 169 Here is an example that shows how multiple header files are parsed 170 from different source directories into a common database. 171 172 ccdoc -db /tmp/ccdoc.db -pkg Utilities project/utils/export/*.h 173 ccdoc -db /tmp/ccdoc.db -pkg Parser project/parser/export/*.h 174 1754 Index Phase 176 177 During the index phase ccdoc analyzes the database to find 178 associations between related entities. For example, if class Child 179 derives from class Parent, this phase will find Parent and link it 180 to the Child record so that a link can be generated during the 181 output phase. The index phase is specified by the -index switch. 182 183 If the index phase is not run, the output will contain no links. 184 185 186 Switch Description 187 ============== =============================== 188 -db <file> The name of the ccdoc database. 189 190 -index Generate the indices. 191 ============== =============================== 192 193 Here is a use-case that shows how generate an index for a database. 194 195 ccdoc -db /tmp/ccdoc.db -index 196 1975 Output Phase 198 199 During the output phase, ccdoc generates HTML from the database. 200 This phase is optional. A user could develop their db reader and 201 output any another format (like XML). The output phase is specified 202 by the -htm or the -html switch. 203 204 After this phase is run, a top level file called 205 ccdoc.<root>.pkg.html will exist in the specified html path. 206 207 Switch Description 208 ================== ====================================================== 209 -bg <color> The background color. The default is the default for 210 the browser. 211 212 -db <file> The name of the ccdoc database. 213 214 -dospaths The file paths contain backslashes that need to be 215 converted to forwards slashes for HTML. 216 217 -htm <prefix>, 218 -html <prefix> The HTML path prefix. This is used to designate the 219 path where the HTML files will be stored. The directory 220 suffix must be included if this is a directory path. 221 Always use a forward slash to separate directories, 222 even when you are running under a DOS window, because 223 the HTTP path hierarchy separator is a forward slash. 224 225 -fg <color> Same as -fgtext. 226 227 -fgtext <color> The foreground text color. The default is the default 228 for the browser. 229 230 -fglink <color> The foreground link color. The default is the default 231 for the browser. 232 233 -fgvlink <color> The foreground vlink color. The default is the default 234 for the browser. These are used links. 235 236 -header <file> The HTML used for the customized header just after 237 the <body> stmt. This is where clients insert their own 238 custom information on each page. See the -meta command 239 for information on how to insert meta variables in 240 the <head> section. 241 242 -imageurl <URL>, 243 -imgurl <URL> The URL that describes of the GIF images. This 244 version of ccdoc does not use images so this switch 245 has no effect. 246 247 -[no]macros Deprecated. Same as -[no]rptmac. 248 249 -maxpathlen <num> Maximum file path size. The default is 128. When the 250 file path size exceeds the limit, the file name 251 is truncated and a checksum is added to guarantee 252 that the file name is unique. If maxpathlen is set 253 to zero, no limit checking is performed. 254 255 -meta <file> The HTML used for the customized header just after 256 the <head> stmt. This is where clients insert their own 257 custom information for meta variables on each page. 258 If -meta is specified, ccdoc will not generate the 259 the http-equiv meta variable for HTML 4.01 compliance 260 and it will ignore the -rptctcs. 261 262 -[no]private Deprecated. Same as -[no]rptpri. 263 264 -[no]protected Deprecated. Same as -[no]rptpro. 265 266 -[no]public Deprecated. Same as -[no]rptpub. 267 268 -root <name> Change the name of the root package from 'root' to 269 something else. 270 271 -rootfile <name> Change the top level output file name from 272 <prefix>ccdoc.root.pkg.html to whatever the user 273 wants. This can be used to create the ccdoc.index.html 274 file by specifying: -rootfile ccdoc.index.html. 275 This switch allows you to completely specify the 276 path. The -html prefix is ignored. 277 278 -rootpurl <URL> 279 -rooturl <URL> The hyperlink for the parent of the root package. 280 Setting this allows the generated HTML to seamlessly 281 integrate to a higher level document by providing a back 282 link to the users parent page. 283 284 -[no]rptcfuns Report comments for undocumented namespaces. When 285 -rptcfuns is specified, all related namespaces 286 comments are reported. This includes namespaces 287 that do not contain ccdoc comments which can be 288 somewhat busy. When -norptcfuns is specified, only 289 related namespaces with ccdoc comments are reported. 290 The only exception is when none of the namespaces 291 have ccdoc comments. In that case, only the first 292 undocumented namespace is reported (for backward 293 compatibility). The default is -norptcfuns. 294 295 -[no]rptcsd Report class summary details. When -rptcsd is 296 specified, the class summary page reports type, access 297 and short description information. When -norptcsd 298 is specified the class summary page only reports the 299 names. The default is -rptcsd. 300 301 -[no]rptcsi <num> The class summary indent switch. Define the indent 302 level of each entry in the class summary report and 303 the contents column. The default indent level is 4. 304 305 -rptctcs <string> Allow the user to specify the Content-Type char set. 306 This allows international languages to be supported. 307 The default char set is "iso-8859-1". 308 This switch is ignored if the -meta switch is specified. 309 310 -rptdefa <string> Set the default string for the author field in 311 top level entities. The default is "unascribed". 312 313 -rptdefasd <string> Set the default string for the automatically generated 314 short description field in top level entities. The 315 default is "automatically generated". 316 317 -rptdefsd <string> Set the default string for the short description 318 field in top level entities. The default is 319 "undocumented". 320 321 -rptdefv <string> Set the default string for the version field in 322 top level entities. The default is "unknown". 323 324 -[no]rptdpa If the package author is not specified, report the 325 author as unascribed. The default is -norptdpa which 326 tells ccdoc to ignore authors on packages unless they 327 are explicitly specified. 328 329 -[no]rptdpd If the package description is not specified, report the 330 description as unknown. The default is -norptdpd which 331 tells ccdoc to ignore descriptions on packages unless 332 they are explicitly specified. 333 334 -[no]rptdpv If the package version is not specified, report the 335 version as unknown. The default is -norptdpv which 336 tells ccdoc to ignore version on packages unless they 337 are explicitly specified. 338 339 -[no]rptfwcf The fixed width code font switch. Use a fixed width 340 font when reporting code fragments. The default is 341 -norptfwcf. 342 343 -[no]rpthpc Report package contents hierarchically like the 344 the class summary page. The default is -rpthpc. 345 346 -[no]rptim Report all inherited methods as though they were 347 defined locally. The default is -rptim. 348 349 -[no]rptmac Report macros. Default is -norptmac because there can be 350 large numbers of guards in header files. If a system is 351 designed with ccdoc in mind, the header guards can be 352 surrounded by ccdoc guards (#ifndef __ccdoc__) which 353 would make this data more useful. 354 355 -[no]rptmac1 Report macros heuristically. This means that ccdoc 356 attempts to filter out header guards and windows 357 DLLIMPORT/DLLEXPORT macros by filtering out macro 358 names with the prefixes: dll_, DLL_, include_, INCLUDE_, 359 included_, INCLUDED_ and the suffixes: dll, _DLL, 360 _h, _H, _hh, _HH, _include, _INCLUDE, _included, 361 _INCLUDED, _included_, _INCLUDED_. 362 363 The default is -norptmac1. 364 When this switch is enabled, it also enables -rptmac. 365 This is a better choice than -rptmac. 366 367 -rptmlci <num> Maximum length of the content ids. This switch is 368 used to avoid strange looking tables of content 369 when the id is very long. 370 371 When the string exceeds this length, only the 372 first <num> characters are printed followed by 373 .. to indicate truncation. 374 375 The default length is 32. A value of zero means 376 don't impose the limit. If no inherited from column 377 exists, the value of the -rptmlcifi is added to make 378 this field bigger. 379 380 -rptmlcifi <num> Maximum length of the contents "inherited from" 381 column id. This switch is used to avoid strange 382 looking tables of content when the parent id is 383 very long. 384 385 When the string exceeds this length, only the 386 first <num> characters are printed followed by 387 .. to indicate truncation. 388 389 The default length is 32. A value of zero means 390 don't impose the limit. 391 392 -[no]rptpri Report private items. The default is -norptpri. 393 394 -[no]rptpro Report protected items. The default is -norptpro. 395 396 -[no]rptpub Report public items. The default is -rptpub. 397 398 -[no]rptsci Report the class information in sorted order. The 399 default is -rptsci. If -norptsci is specified 400 the class contents and details are not sorted. 401 402 -[no]rptsrc Report the source information for each entity 403 in the table of contents. This causes an additional 404 column to be added to the table. The default is 405 -norptsrc because this information is already 406 reported for each entity in its description. It 407 exists to provide debugging support for when no 408 description is generated. 409 410 -[no]rpttyp Report typedefs. Default is -rpttyp. 411 412 -[no]rptun Report unions. Default is -rptun. 413 414 -sourceurl <URL>, 415 -srcurl <URL> The URL where the source files can be found. If this 416 is specified, hyperlinks are created for Source entries. 417 418 -trailer <file> The HTML used for the customized trailer. 419 420 -[no]typedefs Deprecated. Same as -[no]rpttyp. 421 422 -[no]unions Deprecated. Same as -[no]rptun. 423 ================== ====================================================== 424 425 Here is a use case that shows how to generate HTML: 426 427 ccdoc -db ccdoc.db -html webdocs/ -imgurl images/ \ -trailer 428 custom_trailer.html \ -root MyProject -rooturl myproj.htm 429 4306 Running the Program 431 432 This section presents some example flows to help you understand how 433 to use the program more effectively. 434 435 6.1 Simple Flow 436 437 This is the simplest flow. You run all three phases at the same time. 438 439 % ## UNIX: 440 % ccdoc \ 441 -db webdocs/ccdoc.db \ 442 -pkg simple \ 443 *.h \ 444 -index \ 445 -rootfile webdocs/index.html \ 446 -html webdocs/ 447 448 > REM DOS 449 > ccdoc -db webdocs/ccdoc.db -pkg simple *.h -index -rootfile webdocs/index.html -html webdocs/ 450 451 Note that it forces the top level html file to be named index.html which 452 is convenient for most browsers. 453 454 6.2 Typical Flow 455 456 This is the typical for a usage for a system with multiple packages. 457 Each phase is run separately. 458 459 % ### Phase 1a - Parse 460 % ccdoc -db typical.db -pkg typical.utils work/utils/src/*.h 461 % # Don't report missing default constructors. 462 % ccdoc -db typical.db -pkg -nocdsm typical.liba work/liba/src/*.h 463 % # Define a macro that is used for my documentation. 464 % ccdoc -db typical.db -pkg \ 465 -DMY_CCDOC_EXTERNAL typical.libb \ 466 work/libb/src/*.h 467 468 % ### Phase 1b - Parse root level documentation 469 % ccdoc -db typical.db -pkg typical typical.txt 470 471 % ### Phase 2 - Index 472 % ccdoc -db typical.db -index 473 474 % ### Phase 3 - Output 475 %ccdoc \ 476 -db typical.db \ 477 -html webdocs/ \ 478 -rootfile webdocs/index.html \ 479 -srcurl work/ \ 480 -trailer custom.htm 481 4827 Comment Directives 483 484 This section presents a brief overview of the ccdoc comment syntax. 485 486 The directives are summarized in the table below. 487 488 Id Directive Quick Summary 489 == ============= ===================================================== 490 1 /** .. */ Encloses a javadoc style ccdoc comment. 491 2 /**< .. */ Encloses a doxygen style suffix ccdoc comment. 492 3 /*!< .. */ Encloses a doxygen style suffix ccdoc comment. 493 4 //@{ .. //@} Encloses a ccdoc comment for C++ style line comments. 494 5 //@- Single line suffix C++ style comment form. 495 6 ///< Same as //@- (doxygen compatible). 496 7 //!< Same as //@- (doxygen compatible). 497 8 /**@#-*/ Turn off ccdoc token parsing. 498 9 /**@#+*/ Turn on ccdoc token parsing. 499 10 /**@#=<ch>*/ Insert <ch> into the input stream. 500 11 {@link...} The in-line link specification. 501 12 @@ Translate HTML special characters for code fragments. 502 13 @$ Same @link. 503 14 @author Specify an author. 504 15 @deprecated Describes the alternatives to use. 505 16 @exception Deprecated, same as @throws. 506 17 @link,@endlink Generate a hyperlink to a ccdoc entity. 507 18 @param Document a function or class method parameter. 508 19 @pkg Specifies the name of a package. 509 20 @pkgdoc This comment documents a specific package. 510 21 @pkgdoctid Redefine the output title id for a pkgdoc. 511 22 @return Deprecated, same as @returns. 512 23 @returns Documents the return value from a method or function. 513 24 @see Add a hyperlink entry to the See section. 514 25 @since When this became available. 515 26 @suffix This is a suffix comment. 516 27 @throws Document an exception. 517 28 @todo Describes todo information. 518 29 @version The entity version. 519 520 Each directive is described in more detail in the following 521 subsections. 522 523 7.1 /** .. */ 524 525 Indicates javadoc style ccdoc comment that is associated with the 526 next C++ statement (prefix style comment). 527 528 A simple example is shown below: 529 530 /** 531 * This is the brief description that shows up in the table 532 * of contents. 533 * This is where the longer description starts. 534 * @author A. Programmer 535 * @version 1.0 536 */ 537 void function(int a); 538 539 7.2 /**< .. */ 540 541 Indicates the beginning of a ccdoc style comment that is 542 associated with the previous C++ statement (suffix style comment). 543 544 A simple example is shown below: 545 546 void function(int a); 547 /**< 548 * This is the brief description that shows up in the table 549 * of contents. 550 * This is where the longer description starts. 551 * @author A. Programmer 552 * @version 1.0 553 */ 554 555 7.3 /*!< .. */ 556 557 Indicates the beginning of a ccdoc style comment that is 558 associated with the previous C++ statement (suffix style comment). 559 560 A simple example is shown below: 561 562 void function(int a); 563 /*!< 564 * This is the brief description that shows up in the table 565 * of contents. 566 * This is where the longer description starts. 567 * @author A. Programmer 568 * @version 1.0 569 */ 570 571 7.4 //@{ .. //@} 572 573 Specifies that a ccdoc comment is being specified using the '//' 574 comment form as shown below: 575 576 // ================================================ 577 //@{ 578 // This is a ccdoc comment. 579 //@} 580 // ================================================ 581 int foo(); 582 583 This pragma must exist by itself on the line. 584 585 7.5 //@- 586 587 Specifies the single line suffix C++ style comment form. This for 588 is useful for abbreviated comments. Here is an example: 589 590 class Point3D { 591 public: 592 int p1; //@- The x coordinate. 593 int p2; //@- The y coordinate. 594 int p3; //@- The z coordinate. 595 }; 596 597 You can only specify a single line so directives other than 598 "{@link .. }" and "@link .. @endlink" are not supported. 599 600 7.6 ///< 601 602 Specifies the single line suffix C++ style comment form that is 603 compatible with doxygen. This for is useful for abbreviated 604 comments. Here is an example: 605 606 class Point3D { 607 public: 608 int p1; ///< The x coordinate. 609 int p2; ///< The y coordinate. 610 int p3; ///< The z coordinate. 611 }; 612 613 You can only specify a single line so directives other than 614 "{@link .. }" and "@link .. @endlink" are not supported. 615 616 7.7 //!< 617 618 Specifies the single line suffix C++ style comment form that is 619 compatible with doxygen. This for is useful for abbreviated 620 comments. Here is an example: 621 622 class Point3D { 623 public: 624 int p1; //!< The x coordinate. 625 int p2; //!< The y coordinate. 626 int p3; //!< The z coordinate. 627 }; 628 629 You can only specify a single line so directives other than 630 "{@link .. }" and "@link .. @endlink" are not supported. 631 632 7.8 /**@#-*/ 633 634 Turn off ccdoc token parsing. Unlike #ifndef __ccdoc__ this 635 directive can be inserted anywhere. It is especially useful for 636 excluding portions of code that confuse ccdoc. Here is an example 637 of how to use it: 638 639 /**@#-*/ 640 #ifndef FOO 641 insert random junk to generate a compiler error. 642 #endif 643 /**@#+*/ 644 645 This could also be done using the #ifndef pragma as follows: 646 647 #ifndef __ccdoc__ 648 #ifndef FOO 649 insert random junk to generate a compiler error. 650 #endif 651 #endif 652 653 7.9 /**@#+*/ 654 655 Turn ccdoc token processing back on. See 7.10 for usage details. 656 657 7.10 /**@#=<ch>*/ 658 659 Insert a token into the ccdoc input stream to make parsing easier 660 without affecting the source code. This directive is typically 661 used to "fix" macro instantiations that are not terminated by 662 semi-colons as shown in the following example: 663 664 7.10.1 This will confuse ccdoc. 665 #define M(a) a=1; 666 M 667 M 668 class XX; 669 670 7.10.2 This will not confuse ccdoc because we insert semi-colons. 671 #define M(a) a=1; 672 M /**@#=;*/ 673 M /**@#=;*/ 674 class XX; 675 676 7.10.3 Neither will this because we prep it out. 677 #define M(a) a=1; 678 #ifdef __ccdoc__ 679 M 680 M 681 #endif 682 class XX; 683 684 7.10.4 Or this because we put in redundant semi-colons. 685 #define M(a) a=1; 686 M; 687 M; 688 class XX; 689 690 7.11 {@link <entity> <name>} 691 692 This is very similar to the @link directive except that it can be 693 embedded inside comment lines. Like @link, it tells ccdoc to 694 generate a hyperlink to a ccdoc entity. Unlike @link the arguments 695 are not optional. 696 697 You must specify both the entity and the link name. 698 699 You must not embed white space in the '{@link' specification. For 700 example, '{ @ link' is not valid. 701 702 Any number of link specifications are allowed on a single line. 703 704 Invalid {@link...} specifications are output as simple text. 705 706 The example below shows how it is used: 707 708 /** 709 * Look at {@link #fct this} for more information, 710 * you can also look at {@link #fct1 this} or {@link #fct2 this}. 711 */ 712 void fct3(); 713 714 The <entity> is the ccdoc entity to link to. The <name> is the 715 user name of the link. It can consist of one or more tokens. 716 Leading white space is ignored. 717 718 There is a special case for operators. The example below shows how 719 to specify an {@link ..} directive for an operator. 720 721 /** 722 * This is the same as the {@link #operator== equals operator} 723 * for this class. 724 * @param obj The object to compare to for equality. 725 * @returns True if they are equal or false otherwise. 726 * @see #operator== 727 */ 728 bool is_equal(const Class& obj) const; 729 730 Note that there are no spaces between the operator keyword and the 731 operator tokens. 732 733 7.12 @@ <line> 734 735 Translate HTML special characters for creating code fragments. 736 737 Convert '<' to "<" , '>' to ">" and '&' to 738 "&". This is useful for inserting code fragments. Here is an 739 example of how you would use this directive in a comment: 740 741 /** 742 * Here is an example of how to use this directive. 743 *<blockquote> 744 *<pre> 745 *@@ for(int i=0;i<10 && j>3;++i,--j) { 746 *@@ cout << j << " " << i << endl; 747 *@@ } 748 *</pre> 749 *</blockquote> 750 */ 751 752 7.13 @$ <entity> [<name>] 753 754 Same as @link. See section 7.20 for detailed information. 755 756 7.14 @author <name> 757 758 Specifies the author. To specify multiple authors add multiple 759 directives as shown below. 760 761 /** 762 * There are numerous authors. 763 * @author Foo Bar 764 * @author Spam Wombat 765 */ 766 767 If an author is not specified for a package or a class, an entry 768 is generated to an "unascribed" author. 769 770 If there is more than one author, the best practice is to list 771 them chronologically from most recent to earliest. 772 773 7.15 @deprecated <description> 774 775 Specifies that this interface has been deprecated. You should 776 specify what to use as an alternative. The example below shows 777 how to use this directive. 778 779 /** 780 * Get the system time. 781 * @returns The system time. 782 * @deprecated Use get_time_as_string to avoid memory bloat. 783 */ 784 const char* get_time(); 785 786 7.16 @exception <name> <description> 787 788 Deprecated. See @throws for usage information. 789 790 7.17 @link <entity> [<name>] .. [@endlink] 791 792 Generate a hyperlink to a ccdoc entity anywhere in the the code 793 without generating an entry in the See section. 794 795 Here is an example of how it is used: 796 797 /** 798 * This class is closely associated with 799 * @link Utils::Foo my class 800 * and with this @link Utils::Spam my class @endlink and 801 * with @link Utils::Wombat link to wombat 802 * because they both do bar stuff. 803 */ 804 805 The <entity> is the ccdoc entity to link to. The <name> is the 806 user name of the link. It can consist of one or more tokens. 807 Leading white space is ignored. 808 809 If the link name is not specified, the <entity> name is used. 810 811 The @endlink is optional. Note that in the wombat case, the string 812 "link to wombat" is the link text. 813 814 7.18 @param <name> <description> 815 816 Describes a parameter to a function. There should be one @param 817 directive for each argument. The example below shows how to use 818 this. 819 820 /** 821 * This function does stuff. 822 * @param name The name of the object. The description 823 * will span multiple lines until another directive or 824 * the end of the comment is found. 825 * @param aname Another name. 826 */ 827 void do_something(const char* name,const char* x); 828 829 Beware! Ccdoc does not verify that the parameters are valid so it 830 is possible to input invalid parameters. Ccdoc does not verify 831 that the parameter names are the same either as in the example 832 above: aname should be x (or vice-versa). 833 834 The contents of an @param directive can span multiple lines. All 835 lines following an @param directive are included until another 836 ccdoc directive (other than @link and @@) is encountered. The 837 example below shows how this works: 838 839 /** 840 * This shows how @param can span multiple lines. 841 * @param p1 This parameter can have a 842 *@@ value < 10 and > 0. If the value 843 * is out of range, an exception is thrown. 844 * @returns The associated record. 845 */ 846 847 7.19 @pkg <name> 848 849 Specifies the name of the current package. All entities in the 850 file from the directive onward are associated with the package. 851 This pragma can be overridden from the command line by the -pkg 852 switch. 853 854 There is a special package called @null that can be used to 855 specify that the contents of a file are not associated with any 856 package. This is typically used in the file (or files) that 857 contain the package documentation. Typically these are not C++ 858 header files. 859 860 The example below shows how to define the package directive. 861 862 /**@pkg Stuff.Utils */ 863 864 /**@pkg Stuff::Utils */ 865 866 // This file is not part of any package. 867 /**@pkg @null*/ 868 869 Dots '.' or double colons '::' are used to separate hierarchical 870 sub-packages. 871 872 Package documentation is generated using the @pkgdoc directive as 873 shown in the next section. 874 875 7.20 @pkgdoc <path> [<url>] 876 877 Specifies that the current ccdoc comment is associated with a 878 package NOT a C++ entity. 879 880 This directive can be used to define the documentation in the top 881 package by specifying '@top' as the <name>. The old form: [ROOT] 882 is still accepted. 883 884 Dots '.' or double colons '::' are used to separate hierarchical 885 sub-packages. 886 887 If the <url> argument is specified, ccdoc uses that as the link. 888 This is useful for inserting custom pages into the ccdoc document 889 hierarchy but it puts a significant burden on the user to make 890 sure that links to other ccdoc generated files are valid. 891 892 The following example shows how to document several packages. 893 894 // This file is not part of any package. 895 /**@pkg @null*/ 896 897 /** 898 * This is the documentation for the top of 899 * the documentation tree. 900 * @author The Build Team 901 * @version 1.1 902 * @pkg @top 903 */ 904 905 /** 906 * This is the top level package for MyProject. 907 * 908 * It does lots of useful things and contains 909 * many other packages. 910 * @author Ms. MyProject 911 * @version 1.0 912 * @pkgdoc MyProject 913 */ 914 915 /** 916 * This package contains the I/O utilities for 917 * MyProject. 918 * 919 * This is the detailed information about the 920 * I/O utilities package. 921 * @author Mr. IO_Utilities 922 * @version 1.1 923 * @pkgdoc MyProject::IO_Utilities 924 */ 925 926 /** 927 * This package contains the string utilities for 928 * MyProject. 929 * 930 * This is the detailed information about the 931 * string utilities package. 932 * @author Mr. String_Utilities 933 * @version 1.2 934 * @pkgdoc MyProject.String_Utilities http://mysite/String_Utilities.html 935 */ 936 937 It is important to note that the implicit top level package is 938 implied for @pkgdoc paths. 939 940 7.21 @pkgdoctid <name> 941 942 This directive must be specified after @pkgdoc. If it isn't a 943 warning will be generated and the directive will be ignored. 944 945 It allows you to redefine the pkgdoc title id. Normally when a 946 package name is specified the title on the page is "package 947 <name>". With this directive you can change the "package" 948 string to anything you like. 949 950 It was added because some users would like to define different 951 semantics for different packages, for example: some package might 952 be subsystems, others might be modules and still others might 953 really be packages. With this directive you can change the name in 954 the generated HTML file to better reflect package semantics in 955 your environment. 956 957 The example below shows how to define three packages: A, B and C. 958 A is the top level, B and C are children. A will be reported as a 959 "system", B will be reported as a "module" and C will be 960 reported as a "subsystem". 961 962 /** 963 * @pkgdoc A ../doc/A.html 964 * @pkgdoctid system 965 */ 966 /** 967 * @pkgdoc A::B ../doc/A.B.html 968 * @pkgdoctid module 969 */ 970 /** 971 * @pkgdoc A::C ../doc/A.C.html 972 * @pkgdoctid subsystem 973 */ 974 975 7.22 @return <description> 976 977 Deprecated, same as @returns. 978 979 7.23 @returns <description> 980 981 Describes the return value from a function. If there is no return 982 value, do not use @returns. Ccdoc does not verify that you 983 documented the return value correctly. Here is an example of how 984 it is used. 985 986 /** 987 * Get the global value. 988 * @returns The global value. 989 */ 990 static int get_global_value(); 991 992 The contents of an @returns directive can span multiple lines. 993 All lines following an @returns directive are included until 994 another ccdoc directive (other than @link and @@) is encountered. 995 The example below shows how this works: 996 997 /** 998 * This shows how @returns can span multiple lines. 999 * @returns 1000 *@@ Return true if the value is < max or false if the value is >= max. 1001 * For more information about the value click 1002 *@link utils::value here @endlink . 1003 */ 1004 1005 7.24 @see <entity> [<number>] 1006 1007 Associate an entity in the ccdoc database with the entity 1008 currently being described. 1009 1010 It tells ccdoc to generate a hyperlink to a named entity in the 1011 database. If there are multiple entities with the same name, as is 1012 the case with overloaded functions, specify the number of the one 1013 that you want ccdoc to use. The number should be between 0 and the 1014 number of duplicate entities minus 1. If no number is specified, 1015 the first occurrence is used. The example below shows how to use 1016 this directive. 1017 1018 There is an alternate form that allows the user to specify a url 1019 for the entity. This allows hyperlinks to objects that ccdoc 1020 doesn't know about. It is useful for adding links to documents. 1021 1022 There is another alternative form that allows the user to specify 1023 in the current scope using a '#' prefix. This is convenient for 1024 describing method relations within a class. 1025 1026 Packages are not specified in the @see <entity> specification 1027 because they can be changed at run-time. Ccdoc searchs for all C++ 1028 entities that match the specification in all packages. 1029 1030 /** 1031 * Generate three links, one to the class named Foo, 1032 * the second to the second overloaded method 1033 * Spam in the Bar class and the third to a document 1034 * called wombat at the specified URL. 1035 * @see Foo 1036 * @see Bar::Spam 2 1037 * @see <a href=wombat.html>wombat</a> 1038 */ 1039 1040 There is a special case for operators. The example below shows how 1041 to specify an @see link to an operator. 1042 1043 /** 1044 * This is the same as the {@link #operator== equals operator} 1045 * for this class. 1046 * @param obj The object to compare to for equality. 1047 * @returns True if they are equal or false otherwise. 1048 * @see #operator== 1049 */ 1050 bool is_equal(const Class& obj) const; 1051 1052 Note that there are no spaces between the operator keyword and the 1053 operator tokens. 1054 1055 7.25 @since <version> 1056 1057 This is entity has only been available since the specified 1058 version. Ccdoc does not impose any syntax requirements on the 1059 version string so you can use anything you want. 1060 1061 The example below shows how to use this directive. 1062 1063 /** 1064 * This is a new function. 1065 * It does really new stuff. 1066 * @author Foo Bar 1067 * @version 1.0 1068 * @since v1.2 Built: 2001/10/01 1069 */ 1070 void fct(); 1071 1072 7.26 @suffix 1073 1074 This is a suffix style comment, that is, it is attached to the 1075 preceding statement rather than the following statement as shown 1076 in the example below: 1077 1078 class Foo { 1079 public: 1080 /** 1081 * This is the traditional prefix comment form. 1082 */ 1083 void traditional_comment_form(); 1084 1085 //@{ 1086 // This is an alternate prefix comment form. 1087 //@} 1088 void alt_prefix_comment_form(); 1089 1090 void traditional_suffix_comment_form(); 1091 //@{ 1092 // This is the new suffix comment 1093 // form that some folks have requested. 1094 // @suffix 1095 //@} 1096 1097 void alt1_suffix_comment_form(); 1098 /**< 1099 * This is a doxygen compatible suffix comment 1100 * form that some folks have requested. 1101 */ 1102 1103 void alt2_suffix_comment_form(); 1104 /*!< 1105 * This is a doxygen compatible suffix comment 1106 * form that some folks have requested. 1107 */ 1108 1109 void alt3_suffix_comment_form(); //@- Short comment. 1110 void alt4_suffix_comment_form(); ///< Short comment. 1111 void alt5_suffix_comment_form(); //!< Short comment. 1112 }; 1113 1114 The alternative forms (1,2,4,5) are generally preferred for 1115 doxygen compatibility. 1116 1117 7.27 @throws <name> <description> 1118 1119 Specifies that this exception can be thrown by the method. If the 1120 <name> specifies a class in the ccdoc databse, a hyperlink is 1121 added. The example below shows hows to this directive. 1122 1123 /** 1124 * This function does stuff. 1125 * 1126 * Here is more detail about the stuff 1127 * it does. 1128 * @param name The name of the object. 1129 * @returns The object. 1130 * @exception Exception_NullParameter Is thrown 1131 * if name is NULL. 1132 */ 1133 SomeObject GetObject(const char* name); 1134 1135 The contents of an @exception directive can span multiple lines. 1136 All lines following an @exception directive are included until 1137 another ccdoc directive (other than @link and @@) is encountered. 1138 The example below shows how this works: 1139 1140 /** 1141 * This shows how @exception can span multiple lines. 1142 * @exception Port::Exception Is thrown when the program 1143 * runs out of disk space. 1144 */ 1145 void use_disk_space(); 1146 1147 7.28 @todo <description> 1148 1149 Specifies that there are additional things things to be done to 1150 this interface or its implementation. The example below shows 1151 how to use this directive. 1152 1153 /** 1154 * Get the full file by name if it exists. 1155 * @param out The output file name. 1156 * @param in The input file name. 1157 * @returns The full file name of the first file that matches 1158 * the name parameter. If no match is found, an empty 1159 * string is returned. 1160 * @author Foo 1161 * @version 1.0 1162 * @todo Support wild cards in the input name. 1163 */ 1164 void get_full_file_name(string& out,const string& in); 1165 1166 7.29 @version <id> 1167 1168 Specifies the version of the entity. If this directive is not 1169 specified for classes, functions or packages, "unknown" is reported. 1170 11718 Comment Format 1172 1173 The basic comment format is as follows: 1174 1175 Format Description 1176 ======================== =================================== 1177 /** Start of comment. 1178 * <brief description> The brief description is terminated 1179 * by a period followed by a tab, space 1180 * or newline or it is termined by a 1181 * directive. This complies with the 1182 * javadoc syntax. 1183 * 1184 * In older versions of ccdoc the brief 1185 * description was termined by a blank 1186 * line. This behavior can be re-enabled 1187 * by specifying the phase 1 -nojdsds 1188 * switch. 1189 * First blank (all w/s) line. 1190 * 1191 * <full description> Any number of lines with blanks. 1192 */ End of comment. 1193 <C++ entity> The entity that the comment is 1194 associated with (unless it is 1195 a pkgdoc comment). 1196 ======================== =================================== 1197 1198 Each blank line, other than the first one, is treated as a an HTML 1199 paragraph (<p>). The first blank line separates the brief 1200 description from the full description in -nojdsds mode otherwise it 1201 is ignored. 1202 1203 Ccdoc directives can be embedded anywhere in either description but 1204 they must be the first entity on the line. 1205 1206 The full description is optional. 1207 1208 The leading asterisk on each line is optional. 1209 1210 8.1 The simplest possible comment 1211 1212 The example below shows the simplest possible comment forms. 1213 1214 /**Get the age of an employee.*/ 1215 unsigned int age(const char* name); 1216 1217 //@{ Get the birthdate of an employee. //@} 1218 unsigned int birthdate(const char* name); 1219 1220 unsigned num_items(); //@- The number of items. 1221 unsigned num_items1(); ///< The number of items. 1222 unsigned num_items2(); //!< The number of items. 1223 unsigned num_items3(); /**< The number of items. */ 1224 unsigned num_items4(); /*!< The number of items. */ 1225 1226 8.2 A more reasonable example. 1227 1228 The example below shows a more complete example for the function 1229 in 8.1. As you can see, it assumes that age is part of a class or 1230 a namespace called Employee. 1231 1232 /** 1233 * Get an employees age. 1234 * This function is not thread safe because it 1235 * uses statically initialized data. 1236 * 1237 * If the age of the employee is not known, return 1238 * the value 0. The example below shows how to use 1239 * this function. 1240 * <blockquote> 1241 * <pre> 1242 *@@ #include <iostream> 1243 *@@ #include "Employee.h" 1244 *@@ int main(int,char**) { 1245 *@@ cout << "John Doe's age is" 1246 *@@ << Employee::age("John Doe") 1247 *@@ << endl; 1248 *@@ return 0; 1249 *@@ } 1250 * </pre> 1251 * </blockquote> 1252 * @param name The name of the employee. 1253 * @returns The age of the employee or zero if the 1254 * age if the employee is not known. 1255 * @see Employee 1256 * @throws MyExceptions::NullArgException 1257 * if the name argument is NULL. 1258 * @todo Modify this function to accept a std::string 1259 * reference argument to avoid having to check 1260 * for a NULL argument. 1261 */ 1262 unsigned int age(const char* name); 1263 1264 8.3 Alternative comment form 1 1265 1266 Ccdoc allows you to use the C++ single line comment form in 1267 several ways. In this form you specify the beginning and ending of 1268 a comment by using the standard form and prepending the '//'s as 1269 shown below: 1270 1271 ///** 1272 // * This is a simple comment. 1273 // */ 1274 int simple; 1275 1276 8.4 Alternative comment form 2 1277 1278 This form allows you do away with the multi-line comment form 1279 entirely by specifying the ccdoc comments using begin and end 1280 directives as shown in the example below: 1281 1282 // ================================================ 1283 //@{ 1284 // This is a simple comment for foo that uses the 1285 // new single line comment form. 1286 //@} 1287 // ================================================ 1288 int foo(); 1289 1290 8.5 Alternative comment form 3 (suffix) 1291 1292 This form allows you to specify complex ccdoc comments for the 1293 previous C++ statement as shown in the example below: 1294 1295 int foo(); 1296 //@{ 1297 // This is a simple comment for foo(). 1298 // @suffix 1299 //@} 1300 1301 int foo1(); 1302 /**< 1303 * This is a simple comment for foo1(). 1304 */ 1305 1306 int foo2(); 1307 /*!< 1308 * This is a simple comment for foo2(). 1309 */ 1310 1311 8.6 Alternative comment form 4 (single line, suffix) 1312 1313 Specifies the single line suffix C++ style comment form. This for 1314 is useful for abbreviated comments. Here is an example: 1315 1316 class Point3D { 1317 public: 1318 int p1; //@- The x coordinate. 1319 int p2; ///< The y coordinate. 1320 int p3; //!< The z coordinate. 1321 }; 1322 1323 You can only specify a single line so most directives are not 1324 supported. The only supported directives are {@link .. } and 1325 @link .. @endlink. 1326 13279 Package Help 1328 1329 This section describes how to link to ccdoc comments from your 1330 documentation tree. The root level file is ccdoc.root.pkg.html. The 1331 'root' package name can be changed using the -root <name> switch. 1332 1333 In the previous system the root level file was called 1334 ccdoc.index.html. That behavior can be mimic'ed by using the 1335 -rootfile ccdoc.index.html switch. 1336 1337 Here is an example that shows how to create documentation for a 1338 system: 1339 1340 % cat src/rootdoc.txt <<END 1341 /** 1342 * This is the root level documentation. 1343 * @author The Team 1344 * @version 1.2 1345 * @pkgdoc @root 1346 */ 1347 END 1348 % ccdoc -db sys.db \ 1349 -pkg system \ 1350 -html web/ \ 1351 -rooturl http://system/index.html \ 1352 -srcurl http://system/src/ \ 1353 src/rootdoc.txt \ 1354 src/*.h 1355 1356 Here is another example that shows how to create documentation for a 1357 system with a ccdoc.index.html root file: 1358 1359 % cat src/rootdoc.txt <<END 1360 /** 1361 * This is the root level documentation. 1362 * @author The Team 1363 * @version 1.2 1364 * @pkgdoc @root 1365 */ 1366 END 1367 % ccdoc -db sys.db \ 1368 -pkg system \ 1369 -html web/ \ 1370 -rootfile web/ccdoc.index.html \ 1371 -rooturl http://system/index.html \ 1372 -srcurl http://system/src/ \ 1373 src/rootdoc.txt \ 1374 src/*.h 1375 1376 Note that the root file: "http://system/index.html" is NOT 1377 generated by ccdoc. 1378 1379 Also note that the -srcurl tells the browser where to find the 1380 source code. 1381 1382 Each generated documentation file will have a link named 'Home' to 1383 the root url 'http://system/index.html'. 1384 1385 The http://system/index.html can have a link to 1386 web/ccdoc.root.pkg.html to access the ccdoc documentation. 1387 1388************************************************************************ 1389** HELPFUL HINTS ** 1390** ** 1391** To capture this message in an output file called help.log, ** 1392** run this command as: ** 1393** ** 1394** ccdoc -log help.log -nocout -h ** 1395** ** 1396** If you just want to know how to run ccdoc, see section 6 of this ** 1397** help message. ** 1398** ** 1399** If you just want to see some comment examples, see section 8 of ** 1400** this help message. ** 1401** ** 1402************************************************************************ 1403