Previous Next
Creating documentation templates files

Introduction
When you document symbols in your source code, SNiFF+ uses documentation template files to generate documentation frames for each symbol. There is one documentation template file for each type of symbol.
To create documentation template files, complete these steps:

  1. Customize an existing template file or create a new one.
  2. Name it.
  3. Determine where to store it in your file system.
  4. Specify its location in SNiFF+.
Step 1: Customize documentation template files
There are two ways in which you can customize documentation template files:
  • by using HTML tags for layout

  • by using macros to extract information from SNiFF+'s Symbol Table and comments from your source files

In this section, you will find out which HTML tags are recognized by SNiFF+ and which macros you can use for extracting symbolic information and comments.
Using HTML tags in documentation template files
SNiFF+'s Documentation Editor recognizes the following HTML tags:
(In the following list, only the starting tags are shown.)
<p>
<sub>, <sup>
<code>
<b>, <i>, <em>, <cite>, <strong>
<h1> ... <h6>
<center>
<plaintex>
<pre>
<ul>
<ol>
<dt>
<dd>
<body>
<html>
<!--
Note that you can use other HTML tags in your documentation template files as well. You may want to do so if you plan to browse your documentation template files with an HTML browser. SNiFF+ will ignore any HTML tags that are not listed above.
Maintaining formatting (newline) in HTML
Use the
<pre> tag to maintain formatting (newline) in HTML. For example:
<pre><SNiFFINSERT CODE="@FIRST_COMMENT@"></pre>
(The macro used in this example is described below.)
Using macros in documentation template files
You can use the macros listed in the following table to incorporate information from SNiFF+'s Symbol Table into your documentation. Please note that macro expansion only works when the Use Parser Comments for Syntax Highlighting checkbox in the Project Attributes > Parser view is selected.
Each macro is associated with a particular program scope (see table). If you set the macro in an incorrect scope, SNiFF+ will not be able to expand the macro, and you will get an error message when trying to generate documentation frames.
For example, suppose you want to list the base classes of each class in your source code. You would use the @BASE_CLASS_LIST@ macro to do so. Since this macro has a class scope, you would have to set this macro in the documentation template file used for documenting classes. Then, whenever documentation frames are generated for classes in your source code, the @BASE_CLASS_LIST@ macro is expanded in each documentation frame. See also Step 2: Name your documentation template file.
Macros that have a symbol scope can be set in any documentation template file.
(To see how to set macros in documentation template files, please refer to the example template file on page 320)

.
Macro Scope Description
@BASE_CLASS_LIST@
class
Comma-separated list of the base classes of the class.
@BASE_CLASS_FULL_LIST@
class
Numbered list of the base classes of the class.
@CLASSES_IN_FILE@
file
List of all classes in the documentation file's corresponding source file(s). Note that this macro can only be set in the Header.dtmpl template file (located in $SNIFF_DIR/config/docu ).
@COMMENT_BEFORE_DEF@
symbol
Extract the comments that precede the definition of the symbol in the source file.
Note that the characters / and * are not extracted from the comment text.
@COMMENT_AFTER_DEF@
symbol
Extract the first comment lines that follow the definition of the symbol in the source file. Code lines are allowed between the definition of the symbol and the first comment lines.
Note that the characters / and * are not extracted from the comment text.
Note:
We recommend not using both the @COMMENT_BEFORE_DEF@ and @COMMENT_AFTER_DEF@ macros for the same symbol, since comments following the symbol's definition may belong to the next symbol's definition.
To avoid this ambiguity, always place comment lines either before or after a symbol's definition and use the appropriate macro to extract them.
@COMMENT_BEFORE_DEF_
FROM(X)TO(Y)@

symbol
Extract all comments that precede the definition of the symbol and are between the user-defined tags X and Y. These tags must be alphanumeric and part of the comment that is being extracted.
Note that the characters / and * are not extracted from the comment text.
@COMMENT_AFTER_DEF_
FROM(X)TO(Y)@

symbol
Extract all comments that follow the definition of the symbol and are between the user-defined tags X and Y. These tags must be alphanumeric and part of the comment that is being extracted.
Note that the characters / and * are not extracted from the comment text.
Note:
See the note in the description of the @COMMENT_AFTER_DEF@ macro.
@DER_CLASS_LIST@
class
Comma-separated list of the derived classes of the class.
@DER_CLASS_FULL_LIST@
class
Numbered list of the derived classes of the class.
@ENUM_LIST@
enumeration
Comma-separated list of the enumeration items of the enumeration.
@ENUM_FULL_LIST@
enumeration
Numbered list of the enumeration items of the enumeration.
@FIRST_COMMENT@
file
Extract the first comment lines in the source file. These comment lines must be the first non-empty lines in the file.
Note that the characters / and * are not extracted from the comment text.
Note that this macro can only be set in the
Header.dtmpl template file (located in $SNIFF_DIR/config/docu ).
@INSTVAR_LIST@
class
Comma-separated list of the instance variables in the class.
@INSTVAR_FULL_LIST@
class
Numbered list of the instance variables in the class. The signatures of the variables are included in the list.
@METHOD_LIST@
class
Comma-separated list of the methods defined in the class.
@METHOD_FULL_LIST@
class
Numbered list of the methods defined in the class. The signatures of the methods are included in the list.
@PARAM_LIST@
method or function
List of parameter types of a function or method.
@PARAM_LIST_WITH_
NAME@

method or function
List of parameter types and parameter names of a function or method.
@RET_VAL@
method or function
Return value of the function or method.
@SNIFF_DATE@
file
SNiFF+ version date.
@SNIFF_VERSION@
file
SNiFF+ version number.
@SYMBOL_MEMBEROF@
class
Class name of the symbol.
@SYMBOL_NAME@
symbol
Name of the symbol.
@SYMBOL_TYPE@
symbol
Type of the symbol (e.g., instance variable, global variable).
@TYPE_LIST@
class
Comma-separated list of typedefs in the class.
@TYPE_FULL_LIST@
class
Numbered list of typedefs in the class. The signatures of the typedefs are included in the list.

Step 2: Name your documentation template file
There are two points to keep in mind when naming documentation template files:

For example, suppose you have created and want to name a template file for subroutines in FORTRAN. In SNiFF+, the symbol type for subroutines is
subroutine , and you would therefore name the template file subroutine.dtmpl (all template files have the extension dtmpl ). The following table lists the names that you must use for your C/C++, FORTRAN, IDL, Java and Ada documentation template files.

C/C++ FORTRAN IDL Java Ada Default template file/symbol type
macro
--
macro
--
--
Macro
enum
--
enum
--
enum
Enumeration
typedef
--
--
--
typedef
TypeDef
variable
variable
--
--
object
GlobalVariable
function
subroutine
--
--
subprog
GlobalFunction
class
common_block
interface
class
package
Class
struct
block
struct
interface
record
Struct
inst_var
--
attribute
field
pkg object
InstanceVariable
methodDef
method
method
method
pkg subprog def
Method
union
union
union
--
--
Union

The last column in the table lists the names of the default template files used for the listed symbol types. SNiFF+ uses the default template files if it can't find your template files. See also How SNiFF+ searches for documentation template files.
Step 3: Determine where to store template files
You have two options for storing your documentation template files:

For details about storing and specifying the location of template files, please refer to Step 4: Specify the location of template files.
Step 4: Specify the location of template files
For template files stored in a template directory
  1. Create a template directory and use the following table to name its language-specific subdirectories:

    C/C+
    FORTRAN
    IDL
    Java
    Ada
    Ansi_C/C++

    (Create a directory called Ansi_C and, in it, a subdirectory called C++ ).

    FORTRAN_77
    IDL
    Java
    Ada9X

    If your language is not listed in the above table, launch SNiFF+. Then,

  2. Load a project that contains source files in the language you want to document.
  3. Create a language-specific subdirectory and name it according to the name used in the Language drop down in the Symbol Browser, Hierarchy Browser and in the Cross Referencer.
  4. Store your template file in the appropriate language-specific subdirectory.
  5. Enter the template directory's path in the Template Directory field in the Documentation Editor view of the Preferences dialog.
For template files stored in a project directory
  1. Store the template file in the <project>/docu/dtmpl directory. <project> is the name of project directory in the shared source working environment where the project's source files are stored.
  2. Make sure that the Document Template file type has been loaded into the project. If it hasn't, load it into the project.
  3. Add the documentation template file to the project (by choosing the Add/Remove Files to/from <project>... command from the Project menu of the Project Editor).
How SNiFF+ searches for documentation template files
When you document a particular symbol in your source code, SNiFF+ searches for the appropriate documentation template file in three directories:
  • If the Document Template file type is part of the current project, SNiFF+ first searches for the template file in the directory specified by the file type's Directory attribute (default value is /docu/tmpl ).

  • If the file isn't found, SNiFF+ continues searching for it in the template directory specified in the Template Directory field in the Documentation Editor view of the Preferences dialog.

  • If the template file isn't found, SNiFF+ continues searching for it in the default directory ( $SNIFF_DIR/config/docu ). This directory contains default documentation template files. If SNiFF+ cannot find the appropriate template file for the symbol you are documenting, it will use the Default.dtmpl default template file.

To illustrate this procedure, let's use the following figure with three different scenarios:

Click for full size, then use Back button

Scenario 1
You want to document a C++ source file that contains classes, enums and methods. SNiFF+ will use the following template files to create documentation frames:

Scenario 2
You want to document an IDL file that contains interfaces and methods. SNiFF+ will use the following template files to create documentation frames:
  • interface.dtmpl located in <template_directory>/IDL

  • method.dtmpl located in <template_directory>/IDL

Scenario 3
You want to document a FORTRAN file that contains common blocks and methods. SNiFF+ will use the following template files to create documentation frames:
  • Class.dtmpl located in $SNIFF_DIR/config/docu

  • Method.dtmpl located in $SNIFF_DIR/config/docu

Sample documentation template file

Description
<SNiFFSYMBOL TYPE="Class" NAME=" "
SSTATUS="new" DSTATUS="empty"
ATTRIBS="true">

All documentation template files must begin with this header information. This is used for internal management of documentation frames. Do not modify any of its attributes.
<SNiFFSECT SNAME="Symbol Name">
The definition of a Section in the symbol's documentation frame is contained between the start tag (code to the left) and
</SNiFFSECT> .
This particular Section is called Symbol Name. It tells SNiFF+ to insert the name of the symbol at the top of the documentation frame.
Do not modify a Section's start tag.
<center>
<h2>
You can change or add HTML tags in any Sections as desired.
<SNiFFINSERT CODE="@SYMBOL_NAME@">
SNiFF+ macro directive that tells SNiFF+ to expand the macro @SYMBOL_NAME@.
The expanded macro is then inserted after the directive's end tag.
Macros can be set anywhere after a template file's header information.
</h2>
</center>
</SNiFFSECT>

<SNiFFSECT SNAME="Symbol Sign">
<center>
<h4>
<SNiFFINSERT CODE="@RET_VAL@">
<SNiFFINSERT CODE="@SYMBOL_MEMBEROF@">::
<SNiFFINSERT CODE="@SYMBOL_NAME@">(
<SNiFFINSERT CODE="@PARAM_LIST@">)
</h4>
</center>
</SNiFFSECT>
This particular Section is called Symbol Sign. It tells SNiFF+ to insert the signature of the symbol right below its name.
Do not modify any of the attributes in this Section's definition.
HTML tags are used for layout.
<SNiFFSECT SNAME="Parameters">

<h4> Parameters:
<em><SNiFFINSERT CODE="@PARAM_LIST@"></em>
</h4>
This Section is the first one in the documentation frame that contains editable text (see below).
The Section Identifier for this Section is Parameters.
Note that you can modify the name of this section (given by SNAME attribute). In general, you can modify the SNAME attribute for all sections except for Symbol Name and Symbol Sign.
<SNiFFSECTT>
<pre>XXXXX_Parameters </pre>
</SNiFFSECTT>
The definition of the Section Text field of a Section is contained between <SNiFFSECTT> and
</SNiFFSECTT>.
Text contained in the Section Text field is editable in the Documentation Editor.
</SNiFFSECT>

</SNiFFSYMBOL>
All documentation template files must end with this end tag.