Isis 3 Documentation

Introduction | Mandatory Commands | Useful Commands | Example Header | Example Implementation | HTML Quick Reference

The following list are additional tags that may be useful in documenting your code. Tags not appearing in this list or the list of mandatory tags are generally forbidden either because of the documentation rules (such as documentation must appear directly before or after the entity being documented) or because the usage is restricted to the documentation system managers (such as creating new categorization groups). Forbidden tags include: mainpage, defgroup, class, fn, enum, struct, and other tags that are unecessary if documentation is positioned next to the entity it documents.

Formatting:

@a <argument>: Format argument in a special font.

@b <word>: Display the argument word in bold. Equivilant to HTML <b>word</b>

@c <word>: Display the argument word in typewriter font. <tt>word</tt>

@code: Start a block of code. A code block is treated differently than regular text. It is interpreted as C/C++ code. The names of classes and members are hyperlinked to their documentation.

@endcode: End a code block after starting it with the @code command.

@e <word>: Display "word" in italics. <em>word</em> or <i>word</i>

@f$: Mark the beginning or end of an in-text formula. All formulas should be in between @f$ commands. For example:

This example results in the display of the distance equation.

@f[: Mark the start of a long formula that is displayed centered on a separate line.

@f]: Mark the end of a long formula that is displayed on a separate line.

@n: Force a new line.

\$, \@, \\, \&, \<, \>, \#, \%: These commands write the character after the first '\' symbol to the output. These characters need to be escaped because they have special meanings in HTML, XML, and/or Doxygen.

Top

Messages:

@attention { attention text }: Start a paragraph where a message that needs attention may be entered. Ends when a blank line is encountered or some other sectioning device.

@note { text }: Start a paragraph where a note can be entered. The paragraph will be indented.

@par [( paragraph title )] { paragraph }: Start a paragraph with a user defined heading. The heading extends until the end of a line. The paragraph following the command will be indented.

@remarks { remarks text }>: Start a paragraph where one or more remarks may be entered.

@warning { warning message }: Start a paragraph where one or more warnings may be entered.

Top

Code Documentation:

@brief { description }: Start a paragraph where a brief description may be entered. NOTE: If you do not use the @brief command, your first sentence (ending with a .) will be used as the brief description. When appearing in output documentation with your long description, the brief description (marked by @brief or the first line of your long description) will appear on its own line above the long description and will not be repeated.

@date <$Date$ | YYYY-MM-DD> { Optional comment }: Start a paragraph where one or more dates may be entered. You may use the CVS date command to insert the last file modification date from CVS or enter your own date using the ISO 8601 date format.

@dir [<path fragment>]: Directory documentation. The "path fragment" argument should the directory name and enough of the path to be unique with respect to the other directories in the project.

@hideinitializer: By default, the value of a define and the initializer of a variable are displayed unless they are longer than 30 lines. By putting this command in a comment block of a define or variable, the initializer is always hidden.

@name ( header ): This command turns a document block into a header definition of a member group. The comment block should be followed by a //@{...//@} block containing the members of the group.

If a compound (e.g. a class or file) has many members, it is often desired to group them together. Doxygen already automatically groups things together on type and protection level, but maybe you feel that this is not enough or that that default grouping is wrong. For instance, because you feel that members of different (syntactic) types belong to the same (semantic) group. A member group is defined by a

  //@{
  ...
  //@}
  

block or a

  /*@{*/
  ...
  /*@}*/
  

block if you prefer C style comments. Note that the members of the group should be physcially inside the member group's body.

Before the opening marker of a block a separate documentation block may be placed. This block should contain the @name command and is used to specify the title of the group. Optionally, the documentation block may also contain more detailed information about the group.

Nesting of member groups is not allowed.

If all members of a member group inside a class have the same type and protection level (for instance all are static public members), then the whole member group is displayed as a subgroup of the type/protection level group (the group is displayed as a subsection of the "Static Public Members" section for instance). If two or more members have different types, then the group is put at the same level as the automatically generated groups. If you want to force all member-groups of a class to be at the top level, you should put a @nosubgrouping command inside the documentation of the class.

@nosubgrouping: This command can be put in the documentation of a class. It can be used in combination with member grouping to avoid that doxygen put a member group as a subgroup of a Public/Protected/Private... section.

@overload [( function declaration )]: This command can be used to generate the following standard text for an overloaded member function: 'This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.' The overload command does not work inside a one-line comment.

@post { description of the post-condition }: Starts a paragraph where the post-condition of an entity can be described. The paragraph will be indented.

@pre { description of the pre-condition }: Starts a paragraph where the pre-condition of an entity can be described. The paragraph will be indented.

@showinitializer: By default, the value of a define and the initializer of a variable are only displayed if they are less than 30 lines long. By putting this command in a comment block of a define or variable, the initializer is shown unconditionally.

@since YYYY.MM.DD: This tag can be used to specify since when an entity has been avaliable.

@test { paragraph describing a test case }: Starts a paragraph where a test can be described. The description will also add the test case to a separate test list. The two instances of the description will be cross-referenced.

Top

Including & Linking Files:

@file <file-name>: Indicates that a comment block contains documentation for a source or header file with name <name>.The documentation of global functions, variables, typedefs, and enums will only be included in the output if the file they are in is documented as well.

@htmlinclude <file-name>: This command includes the file as is in the HTML documentation.

@image <format> <file> ["Caption"][<size-indication>=<size>]

Syntax

• format: html
• file: image filename, no path
• caption: brief description of the image, required, quoted
• size indication: width | height
• size: integer number of pixels
• size indication: width | height

Conventions

• image file names: Object name + _ + filename (e.g., Statistics_graph.png)
• image file locations: assets directory beneath the Object source code directory (e.g., $ISISROOT/src/base/obj/Statistics/assets/)

Inserts an image into the documentation. Image files must be in the assets directory beneath the Isis Object source code($ISISROOT/src/*/obj/*). If the image is found, it will be copied to the correct output directory.

This command is output format-specific, so if you want to insert an image into generated documentation for more than one format, you'll have to enter the command for each format. The format values supported are html and latex, however Isis documentation is not generated in latex format, so html should be the only format specified. You can also use a URL to specify image location, but doxygen will not check for existance or copy it into a directory for you. The last argument is used to specify width and height of the image. The image format for HTML is limited to what your browser supports. Doxygen does not check if the image is in the correct format.

@include <file-name> and @includelineno <file-name>: This command can be used to include a source file as a block of code. The command takes the name of the include file or the line number as an argument. Source files or directories can be specified by using the EXAMPLE_PATH tag in the doxygen configuration file.

@dontinclude <file-name>: This command can be used to parse a source file without actually verbatim including it (as @include does). This is useful if you want to divide the source file into smaller pieces and add documentation between the pieces.

@link <link-object>: The links that are automatically generated in doxygen always have the name of the object they point to as link-text. The link command can be used to create a link to an object with a user-specified link-text. This command has a matching @endlink command.

@endlink: Ends a link that was started with the @link command.

@skip ( pattern ): This command searches line-by-line through the example that was last included using @include or @dontinclude until it finds a line that contains the specified pattern.

@line ( pattern ): This command searches line by line through the example that was last included using @include and @dontinclude until it finds a non-blank line. If that line contains the specified pattern, it is written to the output.

@skipline ( pattern ): This command searches line-by-line through the example that was last included using @include or @dontinclude until it finds a line that contains the specified pattern. It then writes the line to the output. The @skipline command is equivalent to @skip followed by a @line.

@if <section-label>: Starts a conditional documentation section. This section ends with a matching @endif command. Conditional documentation is disabled by default. To enable it, you must put the section label after the ENABLED_SECTIONS tag in the doxygen configuration file.

@elseif: Starts a conditional documentation section if the previous section was not enabled. A conditional section is disabled by default. To enable it, you must put the section-label after the ENABLED_SECTIONS tag in the configuration file. Conditional blocks can be nested with proper ending commands. (@endif, @ifnot, @else, @elseif).

@else: Starts a conditional section if the previous section was not enabled. The previous should have started with an @if, @ifnot, or @elseif command.

@endif: Ends a conditional documentation statement after beginning it with the @if or @elseif commands.

@ifnot <section-label>: Starts a conditional documentation section. This section ends with a matching @endif command. This conditional statement is enabled by default. To disable it, you must put the section label after the ENABLED_SECTIONS tag in the doxygen configuration file.

@until ( pattern ): This command writes all lines of the example that was last included using @include or @dontinclude to the output, until it finds a line containing the specified pattern. The line containing the pattern will be written as well.

Document History