Using Source Code Tags to Enhance LabWindows/CVI Code Documentation
PrintOverview
LabWindows/CVI offers various source code documentation tools to make the code writing process easier and more convenient for developers. One of these tools is Source Code Tags, introduced in LabWindows/CVI 8.0.
Source code tags, declared using the /// keyword in .c files, provide developers with a convenient way to associate help with functions and parameters. Upon successful compilation, this information will be available in the function prototype tooltips where developers can view context-sensitive help for each function and parameter or even declare variables for parameters. In addition, user-defined functions can take advantage of source code completion options thus reducing the need to reference external documentation during the development process.
This tutorial offers a detailed look at source code tags, including example use cases.
Table of Contents
Source Code Tags
LabWindows/CVI supports the following source code tags:
| Source Code Tag | Description |
| HIFN | Define inline function help |
| HIPAR | Define inline parameter help |
| HIRET | Define inline function return value help |
| ARRAY | Define array parameter |
| OUT | Define output parameter |
The HIFN, HIPAR and HRET tags all support the use of plain text or HTML to define function help within each tag. In addition, you may use the HIFN, HIPAR, or HRET tag more than once for each function/parameter/return value, since the help from all instances of each tag will be merged into one help description.
Tip: To insert an empty line in the help description, use the HIFN, HIPAR, or HRET tag with no help text specified.
Adding Function Help
First, you can add inline function help using the HIFN tag. The structure of the HIFN tag is as follows:
/// HIFN help text
Example
/// HIFN<HTML><BODY><FONT COLOR=RED><H3>Function Fn1()</H3></FONT>
/// HIFN
/// HIFN This is my HTML help for function <B>Fn1</B>.
/// HIFN </BODY></HTML>
int Fn1(int a)
{
return Fn1(a);
}
Compile the code, position the cursor on the function name and select menu Edit » Show Prototype (or press Ctrl+Shift+Space). The function prototype tooltip will show. Click on the question mark button (or press F1) to bring up the function help.
Figure 1. Function HTML Help Using HIFN Tag
Adding Parameter Help
Next, you can add inline parameter help using the HIPAR tag. The structure of the HIPAR tag is as follows:
/// HIPAR paramName/help text
Example
/// HIPAR a/<HTML><BODY><FONT COLOR=RED><H3>Parameter A</H3></FONT>
/// HIPAR a/This is my HTML help for parameter <B>A</B>.
/// HIPAR a/</BODY></HTML>
int Fn1(int a)
{
return Fn1(a);
}
Compile the code, position the cursor on the function parameter and select menu Edit » Show Prototype (or press Ctrl+Shift+Space). The function prototype tooltip will show. Click on the question mark button (or press F1) to bring up the parameter help.
Figure 2. Function HTML Help Using HIPAR Tag
Adding Return Value Help
You can also add inline function return value help using the HIRET tag. The structure of the HIRET tag is as follows:
/// HIRET help text
Example
/// HIFN <HTML><BODY><FONT COLOR=RED><H3>Parameter A</H3></FONT>
/// HIFN This is my HTML help for parameter <B>A</B>.
/// HIFN </BODY></HTML>
/// HIRET<HTML><BODY><FONT COLOR=GREEN>
/// HIRET This is my HTML help for the return value.</FONT>
/// HIRET </BODY></HTML>
int Fn1(int a)
{
return Fn1(a);
}
Compile the code, position the cursor on the function name and select menu Edit » Show Prototype (or press Ctrl+Shift+Space). The function prototype tooltip will show. Click on the question mark button (or press F1) to bring up the function and return value help.
Figure 3. Function HTML Help Using HIRET Tag
Declaring Array Parameters
By default, the LabWindows/CVI compiler considers any pointer type parameter to be a generic pointer. You can indicate to the compiler that a parameter is an array by using the ARRAY tag. This allows you to declare an array parameter as such instead of as a generic pointer. The structure of the ARRAY tag is as follows:
/// ARRAY arrayName1, arrayName2...
Tip: When using the ARRAY tag, you can specify names of multiple function parameters separated by commas.
Example
/// ARRAY in,out
void TranslateArray(float *in, float *out)
{
// some code
}
void main (void)
{
TranslateArray(in, out);
}
Compile the code. Call the user-defined function from another function in the application. Position the cursor on any function parameter in the function call and select menu Edit » Declare Parameter Variable (or press Ctrl+D). The Declare Variable dialog will show and let you declare an array of floats.
Figure 4. Function HTML Help Using ARRAY Tag
Output Parameters
ANSI-C compilers do not distinguish between an input pointer parameter and an output pointer parameter. In LabWindows/CVI, you can clearly identify an output parameter by using the OUT tag. This allows you to declare a variable for the output parameter with the correct datatype instead of with a generic pointer. The structure of the OUT tag is as follows:
/// OUT outputName1, outputName2...
Tip: When using the OUT tag, you can specify names of multiple function parameters separated by commas.
Example
/// OUT out
void TranslateValue(float in, float *out)
{
// Some code here
}
void main (void)
{
float output;
TranslateValue(in, &output);
}
Compile the code. Call the user-defined function from another function in the application. Position the cursor on any function parameter in the function call and select menu Edit » Declare Parameter Variable (or press Ctrl+D). LabWindows/CVI will declare the appropriate datatype for the output variable.
Figure 5. Function HTML Help Using OUT Tag
Related Links
The proven LabWindows/CVI development environment can make your ANSI C application development more productive with various documentation tools, including source code tags, the ability to generate function panels from headers files, and the ability to generate HTML documentation from function panels.
- LabWindows/CVI 8.1 Online Help - Documentation Tags for Source Code
- Generate LabWindows/CVI Function Panels from Header Files Whitepaper
- Generate HTML Web Documentation from LabWindows/CVI Function Panels Whitepaper
- Evaluate LabWindows/CVI
- LabWindows/CVI Home Page
Reader Comments | Submit a comment »
Legal
This tutorial (this "tutorial") was developed by National Instruments ("NI"). Although technical support of this tutorial may be made available by National Instruments, the content in this tutorial may not be completely tested and verified, and NI does not guarantee its quality in any way or that NI will continue to support this content with each new revision of related products and drivers. THIS TUTORIAL IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND AND SUBJECT TO CERTAIN RESTRICTIONS AS MORE SPECIFICALLY SET FORTH IN NI.COM'S TERMS OF USE (http://ni.com/legal/termsofuse/unitedstates/us/).