Grundlagen

TwinCAT bietet die Möglichkeit, Bibliotheksobjekte mithilfe von Kommentaren zu dokumentieren. Dabei können Sie sowohl die Bibliotheksobjekte selbst als auch die einzelnen Elemente der Bibliotheksobjekte kommentieren:

Innerhalb der Kommentare können Sie beschreiben, welchen Zweck das Objekt/Element hat und wie es vom Bibliotheksanwender genutzt werden kann bzw. soll. Die Dokumentation wird im Bibliotheksverwalter, in dem die Bibliothek eingebunden ist, angezeigt. Die Kommentare können einzeilig (Kommentaroperator „//…“) oder mehrzeilig (Kommentaroperator „(*…*)“) sein.

Generelle Beschreibung von Bibliotheksobjekten

Sie können Bibliotheksobjekte beschreiben, indem Sie einen Kommentar oberhalb der Deklarationszeile des Bibliotheksobjekts hinzufügen. Falls sich oberhalb der Deklarationszeile auch Attribute befinden, können Sie den Kommentar entweder ober- oder unterhalb der Attribute positionieren.

Die generelle Beschreibung von Bibliotheksobjekten wird im Bibliotheksverwalter in der Registerkarte Dokumentation angezeigt.

Folgende Objekte können mithilfe eines generellen Kommentars beschrieben werden:

POU-Objekte (Programm, Funktionsbaustein, Funktion)
Schnittstellen
Methoden, Eigenschaften
Globale Variablenlisten, Parameterlisten
DUT-Objekte (Aufzählung, Struktur, Union, Alias)

Beispiele für die Positionierung der Kommentare:

Generelle Beschreibung eines Funktionsbausteins

// General FB comment
FUNCTION_BLOCK FB_Lib
VAR
…

Generelle Beschreibung einer Globalen Variablenliste

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

Generelle Beschreibung einer Parameterliste

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

	Erweiterte Bibliotheksdokumentation (reStructuredText) Wenn Sie in den Projekteigenschaften der Bibliothek das Dokumentationsformat reStructuredText auswählen und den Kommentartext zur generellen Beschreibung von Bibliotheksobjekten entsprechend der Syntax von reStructuredText auszeichnen, stehen Ihnen weitere vielfältige Möglichkeiten der Dokumentation zur Verfügung. (Siehe Erweitert – reStructuredText)

Beschreibung einzelner Elemente von Bibliotheksobjekten

Neben den Bibliotheksobjekten selbst, können Sie die einzelnen Elemente des Bibliotheksobjekts separat beschreiben, indem Sie die Elemente jeweils mit einem Kommentar versehen. Die Kommentare einzelner Variablen können Sie entweder in der Zeile über der Variablendeklaration oder in derselben Zeile hinter der Variablendeklaration positionieren. Den Rückgabetyp einer Methode oder Funktion können Sie kommentieren, indem Sie den Kommentar in der Zeile der Methodendeklaration hinter dem Rückgabetyp einfügen.

Mithilfe der Tabelle, die im Bibliotheksverwalter in den Registerkarten Eingänge/Ausgänge und Dokumentation abgebildet ist, wird die Dokumentation der einzelnen Elemente eines Bibliotheksobjekts übersichtlich dargestellt. Wenn es sich bei dem Bibliotheksobjekt um eine Parameterliste handelt, ist die Tabelle in den Registerkarten Bibliotheksparameter und Dokumentation dargestellt.

Die Tabelle stellt die Kommentare der folgenden Elemente im Bibliotheksverwalter dar:

Kommentare einzelner Variablen

Ein-/Ausgänge eines POU-Objekts (Programm, Funktionsbaustein, Funktion)
Ein-/Ausgänge einer Methode
Globale Variablen (Globale Variablenliste)
Globale Konstanten (Globale Variablenliste, Parameterliste)
Variablen eines DUT-Objekts (Aufzählungs-, Struktur-, Unionvariablen)

Kommentar des Rückgabetyps (Methode, Funktion)

Beispiele für die Positionierung der Kommentare:

Beschreibung einzelner Funktionsbausteinvariablen

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

Beschreibung des Rückgabetyps einer Methode

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

Beispiele

Struktur

Im folgenden Beispiel sind sowohl die Struktur selbst als auch die einzelnen Variablen der Struktur mit einem Kommentar versehen. Die Kommentare werden im Bibliotheksverwalter angezeigt, wenn die Struktur im unteren Teil des Bibliotheksverwalters fokussiert ist.

// 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

Grundlagen 2:

Globale Variablenliste (GVL)

Im folgenden Beispiel sind sowohl die GVL selbst als auch die einzelnen Variablen der GVL mit einem Kommentar versehen. Die Kommentare werden im Bibliotheksverwalter angezeigt, wenn die GVL im unteren Teil des Bibliotheksverwalters fokussiert ist.

Der Kommentar der GVL selbst befindet sich in diesem Beispiel oberhalb des verwendeten Attributs. Alternativ kann der Kommentar auch unterhalb des Attributs positioniert werden.

(* 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

Grundlagen 3:

Funktionsbaustein mit Methode

Im folgenden Beispiel verfügt ein Funktionsbaustein über Ein-/Ausgangsvariablen sowie über eine Methode. Der Funktionsbaustein und die Methode selbst, die einzelnen Ein-/Ausgangsvariablen des Funktionsbausteins und der Methode sowie der Rückgabetyp der Methode sind mit einem Kommentar versehen. Die Kommentare werden im Bibliotheksverwalter angezeigt, wenn der Funktionsbaustein oder die Methode im unteren Teil des Bibliotheksverwalters fokussiert ist.

Funktionsbaustein:

// 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

Grundlagen 4:

Methode:

// 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

Grundlagen 5:

Funktionsbaustein als Unterklasse

Im folgenden Beispiel ist ein Funktionsbaustein als Unterklasse des oben beschriebenen Funktionsbausteins deklariert. Die Unterklasse selbst sowie die zusätzliche Eingangsvariable sind mit einem Kommentar versehen. Diese Kommentare werden im Bibliotheksverwalter angezeigt, wenn die Unterklasse im unteren Teil des Bibliotheksverwalters fokussiert ist. Zusätzlich werden für die Unterklasse die Variablen der Oberklasse samt Kommentar angezeigt.

// 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

Grundlagen 6: