Using Source Code Tags to Enhance LabWindows/CVI Code Documentation

Publish Date: Feb 22, 2013 | 1 Ratings | 5.00 out of 5 | Print | Submit your review

Overview

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

  1. Source Code Tags
  2. Adding Function Help
  3. Adding Parameter Help
  4. Adding Return Value Help
  5. Declaring Array Parameters
  6. Output Parameters

1. 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.

Back to Top

2. 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

Back to Top

3. 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

Back to Top

4. 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

Back to Top

5. 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

Back to Top

6. 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. 

             

Back to Top

Bookmark & Share


Ratings

Rate this document

Answered Your Question?
Yes No

Submit