Documenting your Code |
Active Web |
 |
|
Documenting your Code |
Active Web |
|
You can include documentation comments in your source code. These comments are a version of the multi-line comments that are recognized by the ScriptDoc tool. The ScriptDoc tool will use these comments to build a set of HTML documentation for your Active Web application.
A ScriptDoc comment consists of the characters between the characters /** that begin the comment and the characters */ that end it. The starting delimiter must be at the start of a line or preceded only by white space. The text can continue onto multiple lines.
/**
* This is the typical format of a ScriptDoc comment.
*/
ScriptDoc comments are recognized anywhere in the source file. Those comments placed before a function statement are assigned to the function. All other comments in the source file are assigned to the file and joined together as one comment.
A ScriptDoc comment is a description followed by tags. The description begins after the starting delimiter /** and continues until the tag section. The starting delimiter must be at the start of a line or preceded only by white space. The tag section starts with the first character @ that begins a line (ignoring leading asterisks, white space and comment separator). The description cannot continue after the tag section begins. There can be any number of tags and some types of tags can be repeated while others cannot. The @param tag shown below starts the tag section:
/**
* This is a ScriptDoc comment.
* @param name the object name.
*/
A tag is a special keyword within a comment that ScriptDoc can process. To be interpreted, a tag must appear at the beginning of a line, ignoring leading asterisks, white space and comment separator (/**). This means you can use the @ character elsewhere in the text and it will not be interpreted as the start of a tag. Each standard tag has associated text, which includes any text following the tag up to, but not including, either the next tag, or the end of the doc comment.
The comment text is written in HTML, that is, it should use HTML entities and can use HTML tags. For example, entities for the less-than (<) and greater-than (>) symbols should be written < and >. Likewise, the ampersand (&) should be written &. The bold HTML tag <b> is shown in the following example.
/**
* This is a <b>ScriptDoc</b> comment.
* @param name the object name.
*/
When ScriptDoc parses a comment, leading asterisk (*) characters on each line are discarded; blanks and tabs preceding the initial asterisk (*) characters are also discarded. If you omit the leading asterisk on a line, all leading white space is removed. Therefore, you should not omit leading asterisks if you want leading white space to kept, such as when indenting sample code with the <pre> tag. Without leading asterisks, the indents are lost in the generated documents, since the leading white space is removed.
The first sentence of each function comment should be a summary sentence, containing a concise but complete description of the function. This sentence ends at the first period that is followed by a blank, tab, or line terminator, or at the first tag. ScriptDoc copies this first sentence to the function summary in the source file generated document page. The first sentence of the file comments (the comments not assigned to a function) is used by ScriptDoc as a summary description of the source file.
Use header tags carefully When writing documentation comments, it's best not to use HTML heading tags such as <H1> and <H2>, because ScriptDoc creates an entire structured document and these structural tags might interfere with the formatting of the generated document.
ScriptDoc parses special tags when they are embedded within a comment. These tags enable you to auto generate a complete, well-formatted API from your source code. The tags start with an "at" sign (@) and are case-sensitive, they must be typed with the uppercase and lowercase letters as shown. A tag must start at the beginning of a line (after any leading spaces and an optional asterisk) or it is treated as normal text. By convention, tags with the same name are grouped together.
The current tags are:
@author name-text
Adds an "Author" entry with the specified name-text to the generated docs. A doc comment may contain multiple @author tags. You can specify one name per @author tag or multiple names per tag. In the former case, ScriptDoc inserts a comma (,) and space between names. In the latter case, the entire text is simply copied to the generated document without being parsed. Therefore, use multiple names per line if you want a localized name separator other than comma.
@date date-text
Adds a release date to the source file document. There can only be one date tag in a source file. All date tags except the first one will be ignored. The date tag must be in the source file comment section and not in a function comment section.
@param parameter-name description
Adds a parameter to the "Parameters" section in the function details. There can be multiple parameter tags in a comment section. The description may be continued on the next line. The 'parameter-name' is the first word after the tag and the description is all subsequent words up to the next comment or the start of the next tag.
@return description
Adds a "Returns" section with the description text in the function details. There can be multiple return tags in a comment section. This text should describe the return type and permissible range of values.
@version version-text
Adds a version to the source file document. There can only be one version tag in a source file. All version tags except the first one will be ignored. The version tag must be in the source file comment section and not in a function comment section.
The first example is of a source file comment. This can be placed anywhere in the source file that script code is permitted and must not immediately precede a function statement.
/**
* A collection of functions to display a dynamic menu.
* These functions provide all the processing required to
* build the menu for the web site pages. This menu
* is modified for each browser based on previous visits to the site.
*
* @author Bill Jones
* @version 1.0
* @date June 2000
*/
The second example is of a function comment. This must be placed immediately preceding the function statement. If there is a line between the end of the comment and the function statement then the comment will be assigned to the file and the function will be un commented.
/**
* Display the drop down menu.
* This function supplies all the HTML code required to
* create a single level drop down menu on mouse over.
* @param name the name of the menu.
* @param menu the menu object holding all menu details.
* @return A string holding all the HTML code for the drop down menu.
*/
function createDropMenu(name, menu) {
Topic ID: 150049