Documentation Conventions

Documentation Conventions

Generated documentation is created by using a “documentation block” within the Qvc subroutine or function. A documentation block begins with “/**” (note two asterisks) and ends with “*/”.

A documentation block immediately follows the script SUB statement and looks like this:

SUB Qvc.EmptyQvd( ...)    
/**  
@version $Id: Qvc_EmptyQvd.qvs  
Text description  
@tags  
*/`

“Text Description” is the value that will be populated in the “Description” field of the generated documentation. Description may span multiple lines. Any line in the documentation block that is not a tag will be included in the description.

@tags are specific tags as follows. Tags should be completely contained on a single script line. There is currently no provision for a tag to span script lines.

• @syntax example
  A syntax example to invoke the member. Optional parameters should be enclosed in square brackets.
  @syntax CALL Qvc.GetFieldValues('vStats', 'LastUpdate', ['Transactions.qvd']);

• @param number description
  Number is the ordinal parameter number starting with 1.
  Description explains the parameter. The type of the parameter should be given as the first word.
  @param 1 String. Variable stem name in which to return values

• @var variableName direction description
  variableName is the name of the variable.
  direction is this an input (in) or an output (out) variable of this member?
  description explains the variable meaning and its default value. Allowable values should be enumerated.
  @var Qvc.Calendar.v.CreateSetVariables in -1/0 (true/false) Should Calendar Set Analysis variables be created? Default is true.

Because Qvc ‘Functions” (QV variables with parameters) do not have a script statement delineating begin and end, the function tags are necessary to substitute for the SUB / END SUB script statements.
@Function functionName
@EndFunction

The @Function tag should appear after “/**” and the @EndFunction must be contained in its own “/*” block. For example:

/**  
@Function Qvc.FileExists  
Returns true if a file exists. This function may only be used in script.  
@syntax LET vExists = $(Qvc.FileExists('dir\filename.ext'));  
@param 1 The relative or absolute file path as string.  
*/  
The function code…  
/*  
@EndFunction  
*/