DOCUMENTING VIS

All computer programs in any language should be well documented. Documenta-tion is intended to indicate the purpose of the program (or program element, such as a subVI) as well as the author of the program. LabVIEW’s graphical structure makes the information flow more obvious than in test-based computer languages, Figure 2.32

Voltage Divider VI used to determine the resistances needed to generate 8 V Vout.

This VI can be used to determine what resistances are needed to generate a Vout of 8 V as shown in Figure 2.32. Of course, this is “a” solution, not “the” solution since other resistor combinations could also be used.

Section 2.6 Documenting VIs 45

Compare the undocumented VI with the documented VI in Figure 2.34. Now it’s obvious what this VI is designed to do.

Figure 2.33

Undocumented block diagram.

Figure 2.34

Documented block diagram.

The differences between Figures 2.33 and 2.34 are as follows:

• The block diagram has a title.

• Controls and indicators have been shown as icons with labels.

• Labels have been added to streams to make it clear what is being calculated.

• The CDB data type converter has been labeled to show why it is needed.

but a few comments on the block diagram can still go a long way toward making a complex program easier to understand.

LabVIEW provides several mechanisms that make it easy to document VIs.

We begin with the simplest: labeling the block diagram and front panel.

2.6.1 Labeling VIs

As a terrible example, consider the completely undocumented VI shown in Figure 2.33. This VI performs a very common calculation, but that wouldn’t be obvious to most of us.

Figure 2.36 Minimally labeled front panel.

Figure 2.37

Thoroughly labeled front panel.

Labeling a block diagram doesn’t take much time, but it makes the VI much easier to comprehend. To add a label to the block diagram, simply double-click in an open area and start typing. The labels can then be moved if needed.

Similarly, the front panel should be labeled to make it clear what the user needs to do. First, the unlabeled front panel is shown in Figure 2.35.

A few labels help a lot, as shown in Figure 2.36.

A little more information can help the user know which values are inputs and how A, B, and C relate to the coefficients of a quadratic equation. The more thor-oughly labeled front panel is shown in Figure 2.37. This version is over-the-top for a

VI created to solve a single problem, but this degree of labeling is appropriate if the VI will be used routinely, especially if it will be used by someone other than the programmer.

2.6.2 Descriptive Information

Labeling the front panel and block diagram is an important part of documenting a VI, but another level of documentation involves providing a name and description for every VI. LabVIEW makes this easy by providing a VI Properties item on the File menu.

Selecting File / VI Properties opens the VI Properties dialog, shown in Figure 2.38. There are a dozen categories of information about every VI, but we want to use the Documentation category, shown in Figure 2.39.

In Figure 2.39 a description has been added that includes the following:

• VI Title

• Author and date Figure 2.35

Unlabeled front panel.

Section 2.6 Documenting VIs 47

• statement of what the VI is intended to do

• information about the data type of the solutions, and why complex double was used

Notice that parts of the description were surrounded by <B> and </B>; this will cause them to be shown in bold characters when the description is displayed.

Two fields were not used in this example:

• Help tag—used to enter an index term for a help system tied to the VI.

• Help path—you can enter a path to an HTML help file in this field. If you include a Help path, the link to Detailed Help is included in the Context Help window.

This description is saved with the VI and is displayed in LabVIEW’s Context Help window if the mouse is moved over the VI’s icon at the top-right corner of the front panel and block diagram (and Context Help is active). The Context Help window for this VI is shown in Figure 2.40. The file name and icon are shown first, then the VI description.

Note: Use Ctrl-H or the menu options Help / Context Help to open the Context Help window.

Figure 2.38 VI Properties dialog.

Figure 2.39 Adding a description to the VI.

Figure 2.40

VI description shown in the Context Help window.

Figure 2.41

The calculations used to find the quadratic roots have been saved as a subVI called Quad Solve subVI.

2.6.3 Descriptions with SubVIs

A quadratic equation solver is a fairly generic piece of computer code, and it is a good candidate for a subVI that can be used in other VIs. In Figure 2.41, the calcula-tions required to compute the roots of the quadratic have been turned into the Quad Solve subVI (creating subVIs is presented in a later chapter).

The description used in Figure 2.39 was also saved with the Quad Solve subVI.

Now, when the Quad Solve subVI is used on any block diagram, any time the programmer moves the mouse over the Quad Solve icon, the Context Help window shows the description of the subVI. This is shown in Figure 2.42.

Figure 2.42

Context Help for the Quad Solve subVI.

Section 2.8 Saving Your Work 49

When VIs are used within other VIs, the descriptions shown in the Context Help window are very useful.

2.7 PRINTING A VI

In a classical programming language, printing the program meant printing a listing of the programming statements. Because LabVIEW is a graphical programming environment, printing the program is a little different, and generally it involves printing some combination of the following:

• the front panel

• the block diagram

• information about the controls on the block diagram

• names of any sub-VI is (none have been used in any examples yet)

If you just want a printout of the current window (either the front panel or the block diagram), use the menu options File / Print Window . . . This approach does not allow you to select options, but it is the quickest way to get a picture of your block diagram or front panel to a printer.

Opening the Print dialog by selecting Print . . . from the File menu (from either the front panel or the block diagram) gives you a lot of control over:

• what is printed

• in what format

• to what destination

For most situations the File / Print Window . . . approach is adequate. If you need more control over printing, additional details are available in the Appendix:

Printing VIs.