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 */`
The $Id$ will be expanded by SVN on first commit and should not be modified thereafter. “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 */