Documentation Comments (doc-comments) are comments with a particular syntax. Any comment in your source code which starts with doc-comment syntax and is just above or just next to a block of code (function, class, variable, method declaration) will become a comment associated with that item.
The syntax to introduce a doc-comment is different for each language, as each language has its own comment syntax.
In Specman each comment line inside code segments must begin with the
symbol (//). vzDoc doc-comments begin and end with
the symbol (//*) at the beginning of a line, with
intermediate lines being valid Specman comments, starting with the
synbol (//). Doc-comments may be multiline, double
line or single line above the associated declaration. A doc-comment
starting with //* may also be put at the end of a
declaration line, but this is overriden by any pre-declaration doc-comment.
The following code illustrates various examples of doc-comments:
<'
//*
// Multiline doc-comment. For simpleStruct with some
// <PRE>
// preformatted stuff x x
// |
// \_/
// </PRE>
// And more non preformatted stuff
// on other lines as well
//*
struct simpleStruct {
myField1 : uint ; //* End of line doc-comment for myField1
//* Single line doc-comment for myField2.
myField2 : byte ;
//* Double line doc-comment for myMethod1.
//* Along with some drivel stuff in it to pad out the lines
myMethod1() is empty ;
// THIS LINE WONT MAKE IT
//* THIS LINE SHOULD NOT APPEAR IN THE DOCUMENTATION
//* Multiline doc-comment for myMethod2. The fairly
// standard version of a doc-comment but with stuff
// round about that we dont want included.
//* And this line is in it too - but not very neat.
// THIS SHOULDN'T BE INCLUDED SINCE IT'S JUST A COMMENT
// BUT SHOULD STILL ALLOW DOC-COMMENT TO BE CAPTURED
myMethod2() is empty ;
// THIS LINE SHOULDN'T APPEAR IN THE DOCUMENTATION
//******************************************
// Multiline doc-comment for myMethod3. But with
// loads of starry bits on the start and end lines
// but that shouldn't matter very much since its still
// legal. And I want to keep these two // characters.
// And with some whitespace between the doc-comment
// and the declaration
//******************************************
myMethod3() is empty ;
myField3WIthNoDocComment : list of byte ;
// DONT INCLUDE THIS LINE
//* Single line comment for emphasized <EM>field5</EM>
myField4 : list of uint ;
// NO DOC-COMMENT FOR myMethod4 - DONT INCLUDE
myMethod4WithNoDocComment() is empty ; // No EOL doc-comment either
//* Single line doc-comment for underlined <U>myMethod5</U>
myMethod5() is empty ;
myMethod6() is empty ; //* End of line doc-comment for myMethod6
};
'>
vzDoc doc-comments begin with the symbol (/**)
followed by optional asterisks and a newline. The last doc-comment line
must begin with asterisks and terminate with
(*/). Any leading * at the
beginning of a doc-comment line are removed. Doc-comments may be
multiline, double line or single line. They may also occur at the end
of a line, but these are overriden by any pre-declaration.
The following shows examples of doc-comments:
/****************************************************
* Multiline block doc-comment. For simpleClass with some
* <PRE>
* preformatted stuff x x
* |
* \_/
* </PRE>
* And more non preformatted stuff
* on other lines as well
*/
class simpleClass {
local string myField1 ; /** End of line doc-comment for myField1 */
/** Single line doc-comment for bold <B>myField2</B> */
public string myField2 ;
/** Double line doc-comment for myMethod1.
And this is the second line */
public function string myMethod1() {
toString = this.name ;
}
/* THIS LINE SHOULDN'T APPEAR IN THE DOCUMENTATION */
/** Multiline doc-comment for myMethod2. The fairly
* standard version of a doc-comment but with stuff
* above that we dont want included.
*/
public task myMethod2() {
}
/*****************************************************
Multiline doc-comment for myMethod3. But with
full line of asterisks on the start and end lines
which should get chopped off.
And with some whitespace between the doc-comment
and the declaration
****************************************************/
public function integer myMethod3() {
}
/** DONT INCLUDE THIS LINE */
/** Single line comment for emphasized <EM>myField3</EM> */
public integer myField3 ;
// NO DOC-COMMENT FOR myMethod4WithNoDocComment - DONT INCLUDE
local function integer myMethod4WithNoDocComment() {
}
/** Single line doc-comment for underlined <U>myMethod5</U> */
public task myMethod5() {}
integer myField4 ; /** End of line doc-comment for myField4 */
}
The following tags are supported:
@author: may be used at the end of a doc-comment
for a class/struct/unit.
@param: may be used at the end of a doc-comment
for a method. (No checking is done for consistency between comment
and code.)
@return: as for @param.
@see: may be used in any doc-comment. It must be
on a line of its own without any other text and of one of the forms:
Hyperlink to full URL address:
@see http://java.sun.com/
Hyperlink to class/struct/unit member in same page:
@see #field_name
Hyperlink to different class/struct/unit:
@see ArbitrationMaster
Remote hyperlink to class/struct/unit member in different page:
@see ArbitrationMaster#setPriority
@version: as for @author.
vzDoc includes a monstrous Vera-only hack with which you can avoid vzDoc parsing problems. If you put in comment lines like...
// vzdoc translate off ...stuff... // vzdoc translate on
... then ...stuff... will be glided over, unparsed.
This is a horrible-but-effective way to glide over things that vzDoc cannot handle.
It only works on Vera files that vzDoc is
asked to parse directly. It doesn't work on
files that get #include'd.