From 7f9169d60847bf0bd4a00179f7538385815f6ff7 Mon Sep 17 00:00:00 2001
From: tmadlener <thomas.madlener@desy.de>
Date: Wed, 2 Oct 2024 16:05:05 +0200
Subject: [PATCH] Add documentation for new capabilities and links

---
 doc/datamodel_syntax.md | 32 ++++++++++++++++++++++++++++++++
 doc/index.rst           |  1 +
 doc/links.md            | 16 ++++++++++------
 3 files changed, 43 insertions(+), 6 deletions(-)

diff --git a/doc/datamodel_syntax.md b/doc/datamodel_syntax.md
index 6386187f7..ac5f1afe2 100644
--- a/doc/datamodel_syntax.md
+++ b/doc/datamodel_syntax.md
@@ -155,6 +155,38 @@ define which `Types` can be used with this interface class, in this case the
 not allow for mutable access to their data.** They can be used in relations
 between objects, just like normal `datatypes`.
 
+## Definition of links
+Podio offers a templated `Link` class ([see here for more details](links.md))
+that allows to link two arbitrary datatypes without having to introduce a
+`OneToOneRelation` or `OneToManyRelation` inside the corresponding datatypes. In
+order to keep the full definition of a datamodel in the YAML file it is possible
+to declare `links` in the YAML file:
+
+```yaml
+    links:
+      ExampleLink:
+      Description: "A link between two (podio generated) objects"
+      Author: "It could be you"
+      From: ExampleHit
+      To: TypeWithEnergy
+```
+
+This definition will yield the following typedefs
+```cpp
+using ExampleLinkCollection = podio::LinkCollection<ExampleHit, TypeWithEnergy>;
+
+using ExampleLink = typename ExampleLinkCollection::value_type;
+// this is equivalent to
+// using ExampleLink = podio::Link<ExampleHit, TypeWithEnergy>;
+
+using MutableExampleLink = typename ExampleLinkCollection::mutable_type;
+// this is equivalent to
+// using MutableExampleLink = podio::MutableLink<ExampleHit, TypeWithEnergy>;
+```
+
+additionally, this will generate the necessary code to enable I/O for this link
+type.
+
 ### Assigning to interface types
 
 Interface types support the same functionality as normal (immutable) datatypes.
diff --git a/doc/index.rst b/doc/index.rst
index 1be94b679..04dd90785 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -15,6 +15,7 @@ Welcome to PODIO's documentation!
    examples.md
    frame.md
    userdata.md
+   links.md
    storage_details.md
    cmake.md
    advanced_topics.md
diff --git a/doc/links.md b/doc/links.md
index c7973ca38..f40d10571 100644
--- a/doc/links.md
+++ b/doc/links.md
@@ -45,12 +45,16 @@ For a more detailed explanation of the internals and the actual implementation
 see [the implementation details](#implementation-details).
 
 ## How to use `Link`s
-Using `Link`s is quite simple. In line with other datatypes that are
-generated by podio all the functionality can be gained by including the
-corresponding `Collection` header. After that it is generally recommended to
-introduce a type alias for easier usage. **As a general rule `Links` need
-to be declared with the default (immutable) types.** Trying to instantiate them
-with `Mutable` types will result in a compilation error.
+Using `Link`s is quite simple. The most straight forward way is to simply
+declare them as part of the datamodel, [as described
+here](datamodel_syntax.md#definition-of-links). That will result in code
+generation that effectiely does what is described here. However, it's not
+strictly necessary to do that in case non-generated code is preferred. In line
+with other datatypes that are generated by podio all the functionality can be
+gained by including the corresponding `Collection` header. After that it is
+generally recommended to introduce a type alias for easier usage. **As a general
+rule `Links` need to be declared with the default (immutable) types.** Trying to
+instantiate them with `Mutable` types will result in a compilation error.
 
 ```cpp
 #include "podio/LinkCollection.h"