reStructuredText
Table of Contents
Introduction
For libraries there must be an API documentation. TwinCAT 3 API documentation is written in reStructuredText. reStructuredText is a simple stupid mark up language. For more information feel free to visit the Beckhoff page: https://infosys.beckhoff.com/content/1033/tc3_plc_intro/4189451147.html.
Scope
For libraries, the minimum is that everything with scope public and protected must have documentation.
All sources in libraries (types, interfaces, functions, classes, programs, GVLs, actions, transitions, public/protected methods and properties) must have a header. If there are pragmas in the source, the header must be written above the pragmas so that the header is the first statement of the source.
The header must start with a short summary and contain at least: the link to the legal notes, the purpose of the source, and if there is one, the return. For the return the following formatting is to be used:
:return: return description
return description
The indentation for all but the first line is important and must be the same.
Parameters and Type-Members
All parameters, type and GVL members must be commented in a library. The comment is placed above the declaration, if there are pragmas for the declaration, the comment must be placed above the pragmas.
Project Properties
The project properties must be filled in for libraries. The description is like a header comment. The library categories are available at https://ekv-app-git-p01.ekvip.de/CNMTC3/cnm-library-categories
Project PropertiesProject Properties
Description Example
This is a TwinCAT 3 library project for an abstract object,
any Coding Monkey Ninja class should be a derivative of this object.
This makes it possible to keep different classes very general like e.g. lists.
.. <legal notes>
legal notes
===========
| SPDX-FileCopyrightText: © 2022 ekvip automation GmbH <info@ekvip.de>
| SPDX-License-Identifier: Apache-2.0
| For details check: Apache-2.0_
.. _Apache-2.0: https://www.apache.org/licenses/LICENSE-2.0
.. </legal notes>
Documentation in the library manager
Examples
Header enumeration Comment in source code
(*
short summary
=============
ComparationResult is an enumeration to unify sorting orders
It's used as return for the methods
:ref:`IComparable.compareTo` and
:ref:`IComparator.compare`.
Type of the enumeration is ``INT``
.. <legal notes>
legal notes
===========
| SPDX-FileCopyrightText: © 2022 ekvip automation GmbH <info@ekvip.de>
| SPDX-License-Identifier: Apache-2.0
| For details check: Apache-2.0_
.. _Apache-2.0: https://www.apache.org/licenses/LICENSE-2.0
.. </legal notes>
enumeration values
==================
*)
|
Documentation in the library manager
Header class Comment in source code
(*
short summary
=============
This is an abstract class that implements the interface :ref:`IObject`.
Every Coding Ninja Monkey class must implement the interface :ref:`IObject`.
To simplify this there is this abstract class to simply derive from it.
This makes it possible to keep different classes very general, such as lists.
.. attention::
**If another implementation for** ``IObject`` **is used, only the other implementation must be used**,
otherwise one runs the risk that the hash code is no longer unique.
.. <legal notes>
legal notes
===========
| SPDX-FileCopyrightText: © 2022 ekvip automation GmbH <info@ekvip.de>
| SPDX-License-Identifier: Apache-2.0
| For details check: Apache-2.0_
.. _Apache-2.0: https://www.apache.org/licenses/LICENSE-2.0
.. </legal notes>
methods and properties
======================
*)
|
Documentation in the library manager
Header method Comment in source code
(*
short summary
=============
The constructor ``FB_init`` is needed to create an unique hash code.
The hash code is a pseudo random number create with a xorshift_ algorithm.
It can be overwritten on derivations, because it will be called implicit, ``SUPER^.FB_init()`` is not required.
For more information check: `Behavoir with derived function blocks`_
.. _Behavoir with derived function blocks: https://infosys.beckhoff.com/content/1033/tc3_plc_intro/5482088715.html?id=6983869892358031022
.. _xorshift: https://en.wikipedia.org/wiki/Xorshift
.. <legal notes>
legal notes
===========
| SPDX-FileCopyrightText: © 2022 ekvip automation GmbH <info@ekvip.de>
| SPDX-License-Identifier: Apache-2.0
| For details check: Apache-2.0_
.. _Apache-2.0: https://www.apache.org/licenses/LICENSE-2.0
.. </legal notes>
parameters
==========
*)
|
Documentation in the library manager
Header method with return Comment in source code
(*
short summary
=============
This method compares a foreign object with the own one, this is needed for sort orders.
The abstract class evaluates every object that is NULL as greater, and all other objects as equal.
.. attention::
For derivations: **If a derived class needs sorting this method must be overwritten.**
.. <legal notes>
legal notes
===========
| SPDX-FileCopyrightText: © 2022 ekvip automation GmbH <info@ekvip.de>
| SPDX-License-Identifier: Apache-2.0
| For details check: Apache-2.0_
.. _Apache-2.0: https://www.apache.org/licenses/LICENSE-2.0
.. </legal notes>
parameters
===========
:return:``SMALLER``: ``THIS`` precedes in order,
``EQUAL``: ``THIS`` and ``object`` at the same position in order,
``GREATER``: ``THIS`` is after in order.
Checkout :ref:`ComparationResult`.
*)
|
Documentation in the library manager
Header property Comment in source code
(*
short summary
=============
This property returns the unique hash code of the object.
The hash code is needed to identify objects that are only addressed via an interface,
e.g. when sorting or when saving between objects
so that the same object does not occur more than once.
.. attention::
For derivations: **This property must not be overwritten**
.. <legal notes>
legal notes
===========
| SPDX-FileCopyrightText: © 2022 ekvip automation GmbH <info@ekvip.de>
| SPDX-License-Identifier: Apache-2.0
| For details check: Apache-2.0_
.. _Apache-2.0: https://www.apache.org/licenses/LICENSE-2.0
.. </legal notes>
*)
|
Documentation in the library manager
