doc: add an example for custom referencetypes

src/server/ua_nodes.h

@@ -24,10 +24,9 @@ extern "C" {
  * Reference are triples of the form ``(source-nodeid, referencetype-nodeid,
  * target-nodeid)``. An example reference between nodes is a
  * ``hasTypeDefinition`` reference between a Variable and its VariableType. Some
- * ReferenceTypes are *hierarchic* and must not form *directed loops*. Every
- * node (except ``Root``) must have at least one hierarchic reference to a
- * parent. See the section on :ref:`ReferenceTypes <referencetypenode>` for more
- * details on possible references and their semantics.
+ * ReferenceTypes are *hierarchic* and must not form *directed loops*. See the
+ * section on :ref:`ReferenceTypes <referencetypenode>` for more details on
+ * possible references and their semantics.
  *
  * The structures defined in this section are *not user-facing*. The interaction
  * with the information model is possible only via the OPC UA :ref:`services`.
@@ -253,11 +252,8 @@ typedef struct {
  *   source and target node
  *
  * The figure below shows the hierarchy of the standard ReferenceTypes (arrows
- * indicate a ``hasSubType`` relation). Please refer to Part 3 of the OPC UA
- * specification for the full semantics of each ReferenceType. The ReferenceType
- * hierarchy can be extended with user-defined ReferenceTypes. Many Companion
- * Specifications for OPC UA define new ReferenceTypes to be used in their
- * domain of interest.
+ * indicate a ``hasSubType`` relation). Refer to Part 3 of the OPC UA
+ * specification for the full semantics of each ReferenceType.
  *
  * .. graphviz::
  *
@@ -323,7 +319,25 @@ typedef struct {
  *    {rank=same alwaysgeneratesevent hasproperty}
  *
  *    }
- */
+ *
+ * The ReferenceType hierarchy can be extended with user-defined ReferenceTypes.
+ * Many Companion Specifications for OPC UA define new ReferenceTypes to be used
+ * in their domain of interest.
+ *
+ * For the following example of custom ReferenceTypes, we attempt to model the
+ * structure of a technical system. For this, we introduce two custom
+ * ReferenceTypes. First, the hierarchical ``contains`` ReferenceType indicates
+ * that a system (represented by an OPC UA object) contains a component (or
+ * subsystem). This gives rise to a tree-structure of containment relations. For
+ * example, the motor (object) is contained in the car and the crankshaft is
+ * contained in the motor. Second, the symmetric ``connectedTo`` ReferenceType
+ * indicates that two components are connected. For example, the motor's
+ * crankshaft is connected to the gear box. Connections are independent of the
+ * containment hierarchy and can induce a general graph-structure. Further
+ * subtypes of ``connectedTo`` could be used to differentiate between physical,
+ * electrical and information related connections. A client can then learn the
+ * layout of a (physical) system represented in an OPC UA information model
+ * based on a common understanding of just two custom reference types. */
 typedef struct {
     UA_NODE_BASEATTRIBUTES
     UA_Boolean isAbstract;