Documentation Tags for Source Code

You can view function matches with the Edit»Show Completions option and view function prototype tooltips with the Edit»Show Prototype option for user-defined functions that you include in source code. If you include user-defined functions, source code browsing must be enabled for the source code completion options to be available.

You also can provide input selections for parameters, declare variables for parameters, and view help text for user-defined functions if you insert special tags in the source code for those functions. These tags also provide a good way for you to document source code.

Note  The following tags might appear similar to the tags you use to generate a function panel from a .h file. However, you can use the following tags only in .c files for the purpose of adding information that appears in function prototype tooltips and generated help. You can use header file tags only in .h files for the purpose of defining a function tree structure.

Use the tags in the following table to document source code and enhance the information available for user-defined functions. Make sure to add these tags before the class or function definition as appropriate.

Tip Tip  Place the cursor before a function definition and select Edit»Insert Construct»Function Documentation Tags or use the <Ctrl-Shift-G> shortcut key in the Source window to insert the /// HIFN, /// HIPAR, and ///HIRET template comment tags automatically. LabWindows/CVI customizes the tags for the function.

The examples in the table use the following user-defined function.

typedef enum
{
     numeric,
     text,
     ring,
     graph
} ctrlType;

int SampleFunction (int controlID, ctrlType controlType, char label[], double *value)

{
     SomeAction;
}

Tag Description
/// HIFN help text Specifies the help text for the function. Use multiple /// HIFN tags to display help text for the function on separate lines. To separate help text with an empty line, use /// HIFN on a line by itself. You also can use HTML tags, but you must enclose the tags in <HTML><BODY></BODY></HTML> tags.

Example
/// HIFN SampleFunction returns the value of a control.
int SampleFunction (int controlID, ctrlType controlType, char label[], double *value)
{
     SomeAction;
}
/// HIPAR paramName/help text Specifies the help text for a parameter. paramName is the name of the parameter for which you want to specify help. Use multiple /// HIPAR tags to display help text for each parameter on separate lines. To separate help text with an empty line, add a /// HIPAR paramName/ tag without any help text. You also can use HTML tags, but you must enclose the tags in <HTML><BODY></BODY></HTML> tags.

You do not need to provide help text for every parameter. If a parameter does not have help text specified for it, LabWindows/CVI displays the function help, if it exists.

Example
/// HIPAR controlID/The name of the control.
/// HIPAR controlType/The type of control. You can specify numeric, text, ring, or graph.
/// HIPAR label/The title of the control.
/// HIPAR label/
/// HIPAR label/You must enclose the label in quotes.
/// HIPAR value/Returns the value of the control you specified.
int SampleFunction (int controlID, ctrlType controlType, char label[], double *value)
{
     SomeAction;
}
/// HIPARV paramName/help text Specifies the help text for a variadic parameter. paramName is the name that will be associated with the variadic parameter in the documentation and is optional. Use multiple /// HIPARV tags to display help text for each parameter on separate lines. If you want multiple lines of help text for a parameter, the /// HIPARV tags must match for each line; for example, if you do not use the optional parameter name, the second line of text must use a tag that does not use the optional parameter name of the /// HIPARV tag. You also can use HTML tags, but you must enclose the tags in <HTML><BODY></BODY></HTML> tags.

You do not need to provide help text for every parameter. If a parameter does not have help text specified for it, LabWindows/CVI displays the function help, if it exists.

Examples
/// HIPARV Help text for variadic parameter description without a name.
static void MyFunc_1(int param, ...)
{
     SomeAction;
}


/// HIPARV variadicParam/Help text for variadic parameter description with name.
static void MyFunc_2(int param, ...)
{
     SomeAction;
}


/// HIPARV Help text for variadic parameter without a name description line 1.
/// HIPARV Help text for variadic parameter without a name description line 2.
static void MyFunc_3(int param, ...)
{
     SomeAction;
}
/// HIRET help text Specifies the help text for the return value. This text appears at the same time as the function help appears. Use multiple /// HIRET tags to display help text for the return value on separate lines. To separate help text with an empty line, use /// HIRET on a line by itself. You also can use HTML tags, but you must enclose the tags in <HTML><BODY></BODY></HTML> tags.

Example
/// HIRET The return value indicates whether the function was successful.
/// HIRET 0 indicates success.
int SampleFunction (int controlID, ctrlType controlType, char label[], double *value)
{
     SomeAction;
}
/// OUT outputName1, outputName2, ... Specifies the parameters of the function that are output parameters. This tag is useful when you need to declare a variable corresponding to that parameter. outputName1 is the name of the parameter. You can specify multiple, comma-separated output parameters per /// OUT tag. You can use only one instance of the /// OUT tag per function definition. If you use more than one /// OUT tag, the last tag overwrites any preceding /// OUT tags. This tag applies only to the function definition that immediately follows the tag name.

Example
/// OUT value
int SampleFunction (int controlID, ctrlType controlType, char label[], double *value)
{
     SomeAction;
}
/// ARRAY arrayName1, arrayName2, ... Specifies the parameters of the function that are arrays. This tag is useful when you need to declare a variable corresponding to that parameter. arrayName1 is the name of the parameter. You can specify multiple, comma-separated parameters per /// ARRAY tag. You can use only one instance of the /// ARRAY tag per function definition. If you use more than one /// ARRAY tag, the last tag overwrites any preceding /// ARRAY tags.

Example
/// ARRAY label

int SampleFunction (int controlID, ctrlType controlType, char label[], double *value)

{
     SomeAction;
}

Generating Function Prototype Tooltip Help

After you insert the comment tags, compile the .c file to enable the function prototype tooltip help.

Generating Help Files

After you insert the comment tags and document the functions, you can generate .html or .xml files to use as help files for the functions. Complete the following steps to generate the help files.

  1. In the Source window, select Build»Target Settings to open the Target Settings dialog box.
  2. Select one of the following options from the Generate help from source option to generate the help files:
    • XML—Generates a .xml file from the code comments and places the file in the same folder as the LabWindows/CVI project. You then can process the .xml file using an XML parser.
    • HTML—Generates .html files from the code comments and places the files in the same folder as the LabWindows/CVI project.
    • HTML & XML—Generates both .xml and .html files from the code comments and places the files in the same folder as the LabWindows/CVI project.
  3. Click the OK button to save the changes and exit the dialog box.

The next time you build the project, LabWindows/CVI generates the designated files and places them in the directory next to the project file in a folder labeled cvicomments.projectname.

WAS THIS ARTICLE HELPFUL?

Not Helpful