TE1030 TwinCAT Documentation Generation

Agenda

1. Motivation
2. TE1030 TwinCAT 3 Documentation Generation
3. Markups
4. Sample
5. Output formats
6. Summary
Motivation

 Generation of a documentation is time consuming

 The documentation must be consistent even after
changes
 Should look the same even if more than one person
writing on the same documentation
Agenda

1. Motivation
2. TE1030 TwinCAT 3 Documentation Generation
3. Markups
4. Sample
5. Output formats
6. Summary
Integration in TwinCAT

TcDocGen
 Enables customers to write the documentation inside their machine
application or library
 Uses specific markups inside the source code comments to mark
relevant information
 Allows to reference inside other documents containing further or
more detailed information
 Generates automatically (partial) class diagrams to show the
dependencies of the code elements
 Generates the documentation for multiple output formats
 Could be easily integrated into existing documentation generation
tool chains because of the DITA support
Integration in TwinCAT

TcDocGen
 Generation of the documentation:

TwinCAT- Projekt

Tc Project PLC C++ Motion IO

TcDocGen API

TcDocGen Viewer

CHM MSHC HTML PDF DITA

3rd Party Tools

Integration in TwinCAT

TcDocGen

output format of
the documentation

documentation comments
Agenda

1. Motivation
2. TE1030 TwinCAT 3 Documentation Generation
3. Markups
4. Sample
5. Output formats
6. Summary
Delimiters

To generate the documentation markups has to be added into

the comments. The following delimiters are allowed:

//! – for single line documentation comments

(*! … *) – for multi line documentation comments in the PLC

/*! … */ – for multi line documentation comments in C++

All documentation lines without specific markups will be handled

as description of the following element.
Markups

The markups used for the documentation generation are XML

based. The used tags are described on the following slides.

If a documentation element has only the length of one line, the

abbreviated form can be used. In this form the XML tags are
written without angled brackets and closing elements. Instead of
the brackets a leading @ will be used to mark the tags. In the
abbreviated form no nested markups are allowed.

Sample:
//! <summary> summary by using the normal form </summary>
//! @summary summary by using the abbreviated form
Markups | Cross references

To create a reference to an other element inside the same documentation the

sign „$“ can be used. If the reference target is not inside the same code
element, a qualified name has to be used. The TcDocGen will automatically
search for this element and create an hyperlink in the documentation.

Sample:
normal form:
//! <summary> use the method $dosomething to do something </summary>

abbreviated form:
//! @summary use the method $dosomething to do something
Markups | description

For marking up a text block as description no further markup besides the

documentation comments delimiters are required.

Sample
normal form:
(*! The first line of a description will automatically detected as summary
For marking up a text block as description no further markup besides the
documentation comments delimiters are required. The summary of a description will
be shown in case the element following the description will became part of a table. *)

abbreviated form:
//! This could be a description of an code element (e.g. an variable in the declaration
editor).
Markups | summary

This markup elements can be used, to markup a line as summary of a code

element. The summary of a description will be shown in case the element
following the description will became part of a table. The first line of a
description will be automatically handled as description.
Sample
normal form:
(*! <summary>This is the summary of the description</summary>
The summary of a description will be shown in case the element following the
description will became part of a table. *)
FUNCTION_BLOCK myFunctionBlock

abbreviated form:
//! @summary This is the summary of the description
//! This could be a description of an code element (optional)
FUNCTION_BLOCK myFunctionBlock
Markups | code

The markup <c> can be used to mark text as source code within an text block.

Sample
normal form:
//! The variable <c>iCount</c> will now be formatted as code within this text block. In
comparison with $iCount <c>iCount</c> will not became a hyperlink.
Markups | code

The markup <code> can be used to mark a text block as source code.

Sample
normal form:
//! <code> iCount := iCount + 1; </code>

also possible in normal form:

//! <code>
iCount := iCount + 1;
//! </code>

abbreviated form:
//! @code iCount := iCount + 1;
Markups | example

The markup <example> can be used to mark a block of text as example.

Sample
normal form:
(*! <example> This is a description of the following example:
<code>iCount := iCount + 1;</code>
In this example the increasing of the variable $iCount by 1 will be shown. </example>*)
Markups | literal

The markup <literal> can be used to mark text as plain text, which should not
be interpreted.

Sample
normal form:
(*! <literal> This is a sample for a description and in-between the <literal>-tags no
cross references or other markups will be detected.</literal>*)

abbreviated form:
//! @literal description in which no other markup or sign will be evaluated
Markups | links within a text block

The markup <see> can be used to create an external link within a text block.
The target of the link will be specified by using a URI (Uniform Resource
Identifier).

Sample
normal form:
(*! To get more information about the TwinCAT 3 Documentation generation please
have a look at <see uri=http://www.beckhoff.de/TE1030>Beckhoff Homepage</link>*)

abbreviated form:
//! @see http://www.beckhoff.de/TE1030
OR
//! @see http://www.beckhoff.de/TE1030 Beckhoff Homepage
Markups | links

The markup <seealso> can be used to create an external link outside of a

text block. The target of the link will be specified by using a URI (Uniform
Resource Identifier).

Sample
normal form:
(*! To get more information about the TwinCAT 3 Documentation generation please
have a look at the Homepage.*)
//! <seealso uri=http://www.beckhoff.de/TE1030> Beckhoff Homepage </ seealso >

abbreviated form:
//! @seealso http://www.beckhoff.de/TE1030
OR
//! @seealso http://www.beckhoff.de/TE1030 Beckhoff Homepage
Markups | link targets

The target of both link types are specified as URI (Uniform Resource
Identifier).

According to the standard RFC 3986 a URI consists of 5 parts:

URI = scheme ":" hierarchical-part [ "?" query ] [ "#" fragment ]
hierarchical-part = "//" authority path-abempty
/ path-absolute
/ path-rootless
/ path-empty

Examples for URIs:

http://www.ietf.org/rfc/rfc2396.txt
ftp://ftp.is.co.za/rfc/rfc1808.txt
file:///C:/TwinCAT/Functions/TE1030/markups.html#links
urn:oasis:names:specification:docbook:dtd:xml:4.1.2
https://tools.ietf.org/pdf/rfc3986.pdf
Markups | param

This markup allows to describe a parameter value of a method. This markup

can be used optional, if the space behind the parameter definition in the
declaration editor is not enough, or to have the complete documentation at the
same place.
Sample:
normal form:
(*!<param name=“bTest”> This parameter is a Boolean Test variable.
</ param >*)
METHOD mExecute : INT
abbreviated form:
//! @param bTest This parameter is a Boolean Test variable.
METHOD mExecute : INT
OR
METHOD mExecute : INT
VAR_INPUT
bTest : BOOL; //! This parameter is a Boolean Test variable.
Markups | returns

This markup allows to describe the return value of a method.

Sample:
normal form:
(*!<returns> The return value if this method has to be greater than 0.
</ returns >*)
METHOD mExecute : INT
…

abbreviated form:
//! @returns The return value if this method has to be greater than 0.
METHOD mExecute : INT
…
Markups | list

This markups can be used to define a list. The following list types are available
unordered list <ul> or ordered list <ol>. Similar to HTML the markup list item
<li> are used for the items of both lists.

Sample:
normal form:
(*!<ul>
<li> content of item 1 </li>
…

<li> content of item n</li></ul>*)

abbreviated form:
(*! @ol
@li content of item 1
…

@li content of item n *)

Markups | table

This markups can be used to define a table. For a table no abbreviated form is
available.

Sample:
normal form:
(*!<table>
<tr>
<th> head colum 1 </th>
<th> head colum 2 </th>
</tr>
<tr>
<td> content of item 1</td>
<td> content of item 2</td>
</tr>
</ table >*)
Markups | audience

This markup allows to define, that the documentation of the following element
can only be generated for a defined user group.

Sample
normal form:
//! This is a sample for a function block which should only available for a specific group
//! <audience> customer </audience>
FUNCTION_BLOCK myFunctionBlock
…

abbreviated form:
//! This is a sample for a function block which should only available for a specific group
//! @audience customer
FUNCTION_BLOCK myFunctionBlock
…
Markups | preliminary

Allows to specify if an section or element is preliminary and subject to

change. This markup element is only a flag and can not contain other internal
information.

Sample
normal form:
//! <preliminary/>
FUNCTION_BLOCK myFunctionBlock
…

abbreviated form:
//! This element is preliminary and subject to change.
//! @preliminary
FUNCTION_BLOCK myFunctionBlock
…
Markups | note

This markup can be used to define a security warning. A note can be of type
information, warning or hazard.

Sample:
normal form:
(*!<note type=“information”> This is the info message.
</note>*)

abbreviated form:
//! @note warning This is the warning message.
Agenda

1. Motivation
2. TE1030 TwinCAT 3 Documentation Generation
3. Markups
4. Sample
5. Output formats
6. Summary
Sample | Plc POU
(*! a program with a simple counter
This is a sample program in which i will increase a counter variable. Of course the description of this program
could be longer than one line *)
PROGRAM MAIN
VAR
btest AT%Q* :BOOL; //! A sample variable not needed for this POU
iCount2: INT; //! This is my counter variable
myPOU : POU //! This is a sample of a FB instanciated within this program
END_VAR

(*! <example> This sample shows how to increase the variable <c>iCount2</c>.
The following code can be used to increase $iCount:
<code>iCount2:=iCount2+1; </code></example>*)
Sample | HTML View in a web browser
Agenda

1. Motivation
2. TE1030 TwinCAT 3 Documentation Generation
3. Tags
4. Markups
5. Output formats
6. Summary
Output formats

 CHM (MS Help System 1)

 HTML

 MSHC (MS Help System 3 – supported from actual VS )

 PDF

 DITA (Darwin Information Typing Architecture)

Output formats | CHM
Agenda

1. Motivation
2. TE1030 TwinCAT 3 Documentation Generation
3. Tags
4. Markups
5. Output formats
6. Summary
Summary

• Automatically generation of a documentation based on the

information within a TwinCAT project
• structural information
• information marked up in the source code comment
• used libraries
• real-time settings
• also NC and IO configuration could be documented
• Generates automatically (partial) class diagrams to show the
dependencies of the code elements
• Allows to reference inside other documents containing further
or more detailed information
• Generation of the documentation in various output formats
possible
• Easily integration into existing documentation tool chains by
supporting DITA