Basics

TwinCAT offers the option of documenting library objects with the aid of comments. You can use comment for the library objects themselves and for the individual elements of the library objects:

You can use the comments to describe the purpose of the object/element and how it can or should be used by the library user. The documentation is displayed in the Library Manager in which the library is integrated. The comments can be single-line (comment operator "//...") or multi-line (comment operator "(*...*)").

General description of library objects

You can describe library objects by adding a comment above the declaration line of the library object. If there are attributes above the declaration line, you can position the comment either above or below the attributes.

The general description of library objects is displayed in the Documentation tab of the Library Manager.

The following objects can be described using a general comment:

POU objects (program, function block, function)
Interfaces
Methods, properties
Global variable lists, parameter lists
DUT objects (enumeration, structure, union, alias)

Samples for positioning the comments:

General description of a function block

// General FB comment
FUNCTION_BLOCK FB_Lib
VAR
…

General description of a global variable list

// General GVL comment. The comment can be placed over possible attributes.
{attribute 'qualified_only'}
VAR_GLOBAL
    fGlobal1     : REAL;
END_VAR

General description of a parameter list

{attribute 'qualified_only'}
// General parameter list comment. The comment can be placed below possible attributes.
VAR_GLOBAL CONSTANT
    cParameter1  : LREAL := 12.34;
END_VAR

	Extended library documentation (reStructuredText) If you select the documentation format reStructuredText in the project properties of the library and mark the comment text for the general description of library objects according to the syntax of reStructuredText, you have many more documentation options. (See Extended – reStructuredText)

Description of individual elements of library objects

In addition to the library objects themselves, you can describe the individual elements of the library object separately by adding a comment to each element. You can position the comments of individual variables either in the line above the variable declaration or in the same line after the variable declaration. You can comment on the return type of a method or function by inserting the comment in the method declaration line after the return type.

The table that is shown in the Input/Output and Documentation tabs of the Library Manager clearly displays the documentation for the individual elements of a library object. If the library object is a parameter list, the table is displayed in the Library Parameters and Documentation tabs.

The table shows the comments for the following elements in the Library Manager:

Comments for individual variables

Inputs/outputs of a POU object (program, function block, function)
Inputs/outputs of a method
Global variables (global variable list)
Global constants (global variable list, parameter list)
Variables of a DUT object (enumeration, structure, union variables)

Comment of the return type (method, function)

Samples for positioning the comments:

Description of individual function block variables

FUNCTION_BLOCK FB_Lib
VAR_INPUT
    // Comment for the first input placed over the declaration
    bInput1  : BOOL;
    bInput2  : BOOL;        // Comment for the second input placed behind the declaration
END_VAR

Description of the return type of a method

// General method comment
METHOD SampleMethod : BOOL  // Comment for the method's return value
VAR_INPUT
    bInput   : BOOL;        // Comment for input variable 
END_VAR

Samples

Structure

In the following sample, both the structure itself and the individual variables of the structure are assigned a comment. The comments are displayed in the Library Manager if the focus is on the structure in the lower part of the Library Manager.

// General structure comment
TYPE ST_Lib :
STRUCT
    bVar    : BOOL := TRUE;  // Comment for BOOL variable
    nVar    : INT  := 123;   (* Comment for INT variable that may also be
                                expanded over several lines. *)
END_STRUCT
END_TYPE

Basics 2:

Global variable list (GVL)

In the following sample, both the GVL itself and the individual variables of the GVL are assigned a comment. The comments are displayed in the Library Manager if the focus is on the GVL in the lower part of the Library Manager.

In this sample, the comment for the GVL itself is above the attribute used. Alternatively, the comment can also be positioned below the attribute.

(* General GVL comment.
The comment can be placed over possible attributes.
And it can be expanded over several lines. *)
{attribute 'qualified_only'}
VAR_GLOBAL
    fGlobal    : REAL := 12.5;  // Comment for the global variable
END_VAR
VAR_GLOBAL CONSTANT
    cGlobal    : INT := 3;      // Comment for the global constant
END_VAR

Basics 3:

Function block with method

In the following sample, a function block has input/output variables and a method. The function block and the method itself, the individual input/output variables of the function block and of the method, and the return type of the method have a comment. The comments are displayed in the Library Manager if the focus is on the function block or the method in the lower part of the Library Manager.

Function block:

// General FB comment
FUNCTION_BLOCK FB_Lib
VAR_IN_OUT
    // Comment for the in-out-variable
    stInOut             : ST_Lib;
END_VAR
VAR_INPUT
    // Comment for this REAL input
    fInput              : REAL := 15.7;
    IbInput    AT%I*    : BOOL;           // Comment for this allocated input
END_VAR
VAR_OUTPUT
    bOutput             :  BOOL := TRUE;  // Comment for this output
END_VAR
VAR
END_VAR

Basics 4:

Method:

// General method comment
METHOD SampleMethod : BOOL   // Comment for the method's return value
VAR_INPUT
    bInput     : BOOL;       // Comment for this BOOL input variable
    fInput     : LREAL;      // Comment for this LREAL input variable
END_VAR

Basics 5:

Function block as subclass

In the following sample, a function block is declared as a subclass of the function block described above. The subclass itself and the additional input variable have a comment. These comments are displayed in the Library Manager if the focus is on the subclass in the lower part of the Library Manager. The variables of the superclass and their comments are also displayed for the subclass.

// General FB comment of the subclass
FUNCTION_BLOCK FB_Lib_Sub EXTENDS FB_Lib
VAR_INPUT
    bInputSub  : BOOL;        // Comment for the input of subclass
END_VAR
VAR_OUTPUT
END_VAR
VAR
END_VAR

Basics 6: