From 9019099e09fdd646e6edf90d98b8430d316badc0 Mon Sep 17 00:00:00 2001
From: tmadlener <thomas.madlener@desy.de>
Date: Thu, 13 Apr 2023 17:19:35 +0200
Subject: [PATCH] Update docstrings

---
 include/podio/DatamodelRegistry.h | 19 +++++++++++++++----
 src/rootUtils.h                   |  2 ++
 2 files changed, 17 insertions(+), 4 deletions(-)

diff --git a/include/podio/DatamodelRegistry.h b/include/podio/DatamodelRegistry.h
index 77f31192b..01a71f383 100644
--- a/include/podio/DatamodelRegistry.h
+++ b/include/podio/DatamodelRegistry.h
@@ -13,7 +13,7 @@ namespace podio {
 /**
  * Type alias for storing the names of all Relations and VectorMembers for all
  * datatypes of an EDM. Populated for each EDM at code generation time.
- * The structure is of each element in the outer vector is:
+ * The structure for each element in the vector is:
  * - get<0>: The name of the datatype
  * - get<1>: The names of all Relations, where OneToManyRelations comes before
  *   OneToOneRelations (in the order as they appear in the YAML file)
@@ -113,15 +113,25 @@ class DatamodelRegistry {
    * @param name The name of the EDM that should be registered
    * @param definition The datamodel definition from which this EDM has been
    * generated in JSON format
-   * @param relationNames the names of the relations and vector members for all
+   * @param relationNames The names of the relations and vector members for all
    * datatypes that are defined for this EDM
    *
+   * @return The datamodel definition index for this datamodel that can be used
+   * for quicker lookup
    */
   size_t registerDatamodel(std::string name, std::string_view definition,
                            const podio::RelationNameMapping& relationNames);
 
   /**
-   * Get the names of the relations and vector members of a datatype
+   * Get the names of the relations and vector members for a given datatype.
+   *
+   * @param typeName The name of the desired type. Can be obtained e.g. via
+   * collection->getValueTypeName()
+   *
+   * @return Relation and vector member names for this type. The order of the
+   * relations is OneToMany before OneToOne relations in the order they appear
+   * in the YAML file. The order of the VectorMembers is as they appear in the
+   * YAML file
    */
   RelationNames getRelationNames(std::string_view typeName) const;
 
@@ -129,7 +139,8 @@ class DatamodelRegistry {
   DatamodelRegistry() = default;
   /// The stored definitions
   std::vector<std::pair<std::string, std::string_view>> m_definitions{};
-
+  /// The names of the relations and vector members for all datatypes that are
+  /// currently loaded
   std::unordered_map<std::string_view, RelationNames> m_relations{};
 };
 } // namespace podio
diff --git a/src/rootUtils.h b/src/rootUtils.h
index 2a8476d8e..24b5b772c 100644
--- a/src/rootUtils.h
+++ b/src/rootUtils.h
@@ -76,6 +76,7 @@ inline std::string refBranch(const std::string& name, size_t index) {
   return name + "#" + std::to_string(index);
 }
 
+/// The branch name for a relation member of a collection
 inline std::string refBranch(const std::string& name, std::string_view relName) {
   return name + "_" + std::string(relName);
 }
@@ -84,6 +85,7 @@ inline std::string vecBranch(const std::string& name, size_t index) {
   return name + "_" + std::to_string(index);
 }
 
+/// The branch name for a vector member of a collection
 inline std::string vecBranch(const std::string& name, std::string_view vecName) {
   return name + "_" + std::string(vecName);
 }