Writing documentation

We use zkdoc and DocFX to convert documentation comments (API reference) and additional documentation written in markdown to HTML. API references are automatically extracted from the source code and transformed into an online reference. In the source code,

use /// as delimiter for documentation above an object (POU, DUT, variable declaration) and
use //< to write the documentation next to a variable declaration, member declaration or enumeration-field declaration

Note

The tags /// and //< are reserved for use in the declaration view and may not be used in the implementation view.

The doc comment may contain Markdown and to be more specific DocFX Flavoured Markdown.

Each method and function block should contain meaningful informations on how to use this function block and method, respectively. Methods that are already documentated in an interface may be left empty if no additional information is required.

Special commands

\copydoc

Copies a documentation block from the object specified by unique identifier and pastes it at the location of the command. This command can be useful to avoid cases where a documentation block would otherwise have to be duplicated or it can be used to extend the documentation of an inherited member.

The unique identifier (uid) can point to a global variable list, program, interface, function block, function, datatype (*, method or property (Everything that is documented by ///). The uid has to follow the following rules

Syntax is <Namespace>.Object or <Namespace>.Object#Method or <Namespace>.Object#Property
It is case sensitive

Note that if the object pointed has be documented for the copying to work, otherwise a error message, with the text \copydoc uid failed - Doc not found is shown instead. If the object can not be found, the text \copydoc uid failed - Item not found. The copydoc command can be used recursively, but zkdoc will throw an exception if it is cyclically (This would cause an endless loop otherwise).

/// \copydoc ZCore.Object#IsBusy
/// 
/// More detailed, specific documentation
METHOD IsBusy : BOOL

Examples

/// Xy contains some variables to showcase how to write documentation 
/// Write a detailed description here, each method or property can be documented by using `///` as well
FUNCTION_BLOCK Xy
VAR
  _var1 : REAL; //< description about var1, use //< to write the documentation next to a member variable
  
  /// description about var2, use /// to write the documentation about a member variable
  _var2 : INT;
  
  /// the description may use
  /// multiple lines
  /// as well
  _var3 : DINT;
  
  _var4 : INT; //< even if the //< delimiter is used
               //< multiple lines are supported
                                         
  /// Also mixing of delimiter 
  _var5 : ZEquipment.ActuatorDigitalDurations; //< is possible
                                               //< with multiple lines
END_VAR

/// An enum
/// Write a detailed description about how the enum
/// is used and where it is utilized.
{attribute 'qualified_only'}
TYPE EnumerationX :
(
  Value1, //< Description about Value1
  Value2, //< Description about Value2
  Value3, //< Description about Value3
);
END_TYPE

/// Detailed information about what the method `method1` is doing and how it may affect the state of the 
/// function bock in use
/// 
/// > [!NOTE] 
/// > We can use NOTE, WARNING, CRITICAL boxes to showcase some important information to the user
METHOD Method1
VAR_INPUT
  input1 : BOOL; //< what does this input do
  
  /// or this one?
  input2 : INT;
END_VAR

Cross referencing

Besides the usual markdown language that may be used in comments for documentation, we also fully support cross references. Here is an example to reference to a method called TestMethod in the function block Test in the library TestLibrary

[link to testMethod](xref:TestLibrary.Test#TestMethod)

The actual link is case sensitive!
The square-brackets part [link to testMethod] defines how the link is displayed
In the curly-brackets the actual link is given.
Cross references have to start with the string xref:
- The default namespace that is used in the library has to be used (e.g. IaAux, IaPlatform).
- (optional) Seperated by a dot from the library name a function block, interface, structure, enum (...) may be given
- (optional) Seperated by a hash one may refer to a method, field (...)

Referencing to html documents

Websites can be references to with almost the same syntax as it is used with cross references, simply do not use xref to link to external websites or documentation topics that are outside of the source code.

[link to a website](https://zeugwerk.at)
[absolute link to documentation topic](/contribute/contribute_code.md)
[relative link to documentation topic](../contribute_code.md)

The actual link is case sensitive!
The square-brackets part [link to a website] defines how the link is displayed
In the curly-brackets the actual link is given. Here https can be used to link to external websites, absolute paths can be used to link starting from the documentation folder as root, relative paths can also be used.

Images

Documentation may contain images that can be linked to using the usual markdown syntax. However, images have to be located in the folder documentation/images

![image_caption](../images/logo.png)

Diagrams

mermaid-js can be used to generate diagrams. Please refer to its documentation or see examples. These lines of code, used in the documentation

```mermaid
stateDiagram-v2
   [*] --> Init: PLC started
   Init --> GoHome: home pressed
   GoHome --> Idle: done
   GoHome --> FaultReaction: aborted
   FaultReaction --> Init: done\nnot initialized
   FaultReaction --> Idle: done
   Idle --> GoHome: home pressed
```

turn into this state diagram

stateDiagram-v2
   [*] --> Init: PLC started
   Init --> GoHome: home pressed
   GoHome --> idle: done
   GoHome --> FaultReaction: aborted
   FaultReaction --> Init: done\nnot initialized
   FaultReaction --> Idle: done
   Idle --> GoHome: home pressed

Table of Contents