[doc] Homogenize the format of the c++ docstrings and add more doxyge…

…n tags in some places (#574) * Improve and homogenize docstrings for the Frame * Improve and homogenize the docstrings for the ROOT / SIO readers & writers * Make internally used only fillParams private * Remove unimplemented public method * Homogenize the RNTuple reader/writer docstrings * Homogenize docstrings * Homogenize the docstrings for the legacy readers * Properly pass environment to sphinx * Use the @note tag for highlighting notes in documentation * Use Note tag also for python API doc * Fix a few more typos and param argument name mismatches * Add not about invalidating references to Frame destructor --------- Co-authored-by: Mateusz Jakub Fila <[email protected]> Co-authored-by: Andre Sailer <[email protected]>
AIDASoft · Apr 9, 2024 · b94cc63 · b94cc63
1 parent 2626082
commit b94cc63
Show file tree

Hide file tree

Showing 26 changed files with 910 additions and 713 deletions.
diff --git a/cmake/podioDoxygen.cmake b/cmake/podioDoxygen.cmake
@@ -6,7 +6,9 @@ if(DOXYGEN_FOUND AND SPHINX_FOUND)
 
   add_custom_target(documentation
                     COMMAND
-                    ${CMAKE_COMMAND} -E env "LD_LIBRARY_PATH=${CMAKE_BINARY_DIR}/src/:$ENV{LD_LIBRARY_PATH};ROOT_INCLUDE_PATH=${CMAKE_SOURCE_DIR}/include;"
+                    ${CMAKE_COMMAND} -E env
+                    "LD_LIBRARY_PATH=${CMAKE_BINARY_DIR}/src/:$ENV{LD_LIBRARY_PATH}"
+                    "ROOT_INCLUDE_PATH=${CMAKE_SOURCE_DIR}/include:$ENV{ROOT_INCLUDE_PATH}"
                     ${SPHINX_BUILD_EXECUTABLE} -M html
                     ${CMAKE_SOURCE_DIR}/doc ${SPHINX_OUTPUT_DIRECTORY}
                     COMMENT "Building documentation" VERBATIM

diff --git a/doc/conf.py b/doc/conf.py
@@ -146,7 +146,11 @@
         "../python",
         "../*/*test_*.py",  # exclude tests
         "../python/podio_version.py",  # exclude convenience module
-    ]
+    ],
+    stdout=subprocess.PIPE,
+    stderr=subprocess.PIPE,
+    env=env,
+    cwd=doc_dir,
 )
 
 print("Done with python API doc generation")
diff --git a/include/podio/CollectionBranches.h b/include/podio/CollectionBranches.h
@@ -7,11 +7,9 @@
 #include <vector>
 
 namespace podio::root_utils {
-/**
- * Small helper struct to collect all branches that are necessary to read or
- * write a collection. Needed to cache the branch pointers and avoid having to
- * get them from a TTree/TChain for every event.
- */
+/// Small helper struct to collect all branches that are necessary to read or
+/// write a collection. Needed to cache the branch pointers and avoid having to
+/// get them from a TTree/TChain for every event.
 struct CollectionBranches {
   TBranch* data{nullptr};
   std::vector<TBranch*> refs{};

diff --git a/include/podio/CollectionBufferFactory.h b/include/podio/CollectionBufferFactory.h
@@ -11,20 +11,19 @@
 
 namespace podio {
 
-/**
- * The CollectionBufferFactory allows to create buffers of known datatypes,
- * which can then be populated by e.g. readers. In order to support schema
- * evolution, the buffers have a version and this factory will also require a
- * schema version to create buffers.
- *
- * It is implemented as a singleton, which is populated at the time a shared
- * datamodel library is loaded. It is assumed that that happens early on in the
- * startup of an application, such that only a single thread will access the
- * factory instance for registering datatypes. Since the necessary creation
- * functions are part of the core datamodel library, this should be very easy to
- * achieve by simply linking to that library. Once the factory is populated it
- * can be safely accessed from multiple threads concurrently to obtain buffers.
- */
+/// The CollectionBufferFactory allows one to create buffers of known datatypes,
+/// which can then be populated by e.g. readers. In order to support schema
+/// evolution, the buffers have a version and this factory will also require a
+/// schema version to create buffers.
+///
+/// It is implemented as a singleton, which is populated at the time a shared
+/// datamodel library is loaded. It is assumed that that happens early on in the
+/// startup of an application, such that only a single thread will access the
+/// factory instance for registering datatypes. Since the necessary creation
+/// functions are part of the core datamodel library, this should be very easy
+/// to achieve by simply linking to that library. Once the factory is populated
+/// it can be safely accessed from multiple threads concurrently to obtain
+/// buffers.
 class CollectionBufferFactory {
   /// Internal storage is a map to an array of creation functions, where the
   /// version determines the place in that array. This should be a viable
@@ -48,29 +47,28 @@ class CollectionBufferFactory {
   /// Get the factory instance
   static CollectionBufferFactory const& instance();
 
-  /**
-   * Create buffers for a given collection type of a given schema version.
-   *
-   * @param collType The collection type name (e.g. from collection->getTypeName())
-   * @param version The schema version the created buffers should have
-   * @param subsetColl Should the buffers be for a subset collection or not
-   *
-   * @return CollectionReadBuffers if a creation function for this collection
-   * type has been registered, otherwise an empty optional
-   */
+  /// Create buffers for a given collection type of a given schema version.
+  ///
+  /// @param collType The collection type name (e.g. from collection->getTypeName())
+  /// @param version The schema version the created buffers should have
+  /// @param subsetColl Should the buffers be for a subset collection or not
+  ///
+  /// @return CollectionReadBuffers if a creation function for this collection
+  /// type has been registered, otherwise an empty optional
   std::optional<podio::CollectionReadBuffers> createBuffers(const std::string& collType, SchemaVersionT version,
                                                             bool subsetColl) const;
-  /**
-   * Register a creation function for a given collection type and schema version.
-   *
-   * @param collType The collection type name (i.e. what
-   * collection->getTypeName() returns)
-   * @param version The schema version for which this creation function is valid
-   * @param creationFunc The function that when invoked returns buffers for this
-   * collection type and schema version. The signature has to be
-   * podio::CollectionReadBuffers(bool) where the boolean parameter steers
-   * whether the buffers are for a subset collection or not.
-   */
+  /// Register a creation function for a given collection type and schema version.
+  ///
+  /// @param collType The collection type name (i.e. what
+  ///                 collection->getTypeName() returns)
+  /// @param version The schema version for which this creation function is
+  ///                valid
+  /// @param creationFunc The function that when invoked returns buffers for
+  ///                     this collection type and schema version. The
+  ///                     signature has to be
+  ///                     podio::CollectionReadBuffers(bool) where the boolean
+  ///                     parameter steers whether the buffers are for a subset
+  ///                     collection or not.
   void registerCreationFunc(const std::string& collType, SchemaVersionT version, const CreationFuncT& creationFunc);
 
 private:

diff --git a/include/podio/CollectionBuffers.h b/include/podio/CollectionBuffers.h
@@ -21,10 +21,8 @@ using UVecPtr = std::unique_ptr<std::vector<T>>;
 using CollRefCollection = std::vector<UVecPtr<podio::ObjectID>>;
 using VectorMembersInfo = std::vector<std::pair<std::string, void*>>;
 
-/**
- * Simple helper struct that bundles all the potentially necessary buffers that
- * are necessary to represent a collection for I/O purposes.
- */
+/// Simple helper struct that bundles all the potentially necessary buffers that
+/// are necessary to represent a collection for I/O purposes.
 struct CollectionWriteBuffers {
   void* data{nullptr};
   void* vecPtr{nullptr};

diff --git a/include/podio/DatamodelRegistry.h b/include/podio/DatamodelRegistry.h
@@ -10,46 +10,40 @@
 
 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:
- * - 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)
- * - get<2>: The names of all VectorMembers (in the order of the file YAML)
- */
+/// 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:
+/// - 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)
+/// - get<2>: The names of all VectorMembers (in the order of the file YAML)
 using RelationNameMapping =
     std::vector<std::tuple<std::string_view, std::vector<std::string_view>, std::vector<std::string_view>>>;
 
-/**
- * Information on the names of the OneTo[One|Many]Relations as well as the
- * VectorMembers of a datatype
- *
- * The contents are populated by the code generation, where we simply generate
- * static vectors that we make available as const& here.
- */
+/// Information on the names of the OneTo[One|Many]Relations as well as the
+/// VectorMembers of a datatype
+///
+/// The contents are populated by the code generation, where we simply generate
+/// static vectors that we make available as const& here.
 struct RelationNames {
   /// The names of the relations (OneToMany before OneToOne)
   const std::vector<std::string_view>& relations;
   /// The names of the vector members
   const std::vector<std::string_view>& vectorMembers;
 };
 
-/**
- * Global registry holding information about datamodels and datatypes defined
- * therein that are currently known by podio (i.e. which have been dynamically
- * loaded).
- *
- * This is a singleton which is (statically) populated during dynamic loading of
- * generated EDMs. In this context an **EDM refers to the shared library** that
- * is compiled from the generated code from a datamodel definition in YAML
- * format. When we refer to a **datamodel** in this context we talk about the
- * entity as a whole, i.e. its definition in a YAML file, but also the concrete
- * implementation as an EDM, as well as all other information that is related to
- * it. In the API of this registry this will be used, unless we want to
- * highlight that we are referring to a specific part of a datamodel.
- */
+/// Global registry holding information about datamodels and datatypes defined
+/// therein that are currently known by podio (i.e. which have been dynamically
+/// loaded).
+///
+/// This is a singleton which is (statically) populated during dynamic loading
+/// of generated EDMs. In this context an **EDM refers to the shared library**
+/// that is compiled from the generated code from a datamodel definition in YAML
+/// format. When we refer to a **datamodel** in this context we talk about the
+/// entity as a whole, i.e. its definition in a YAML file, but also the concrete
+/// implementation as an EDM, as well as all other information that is related
+/// to it. In the API of this registry this will be used, unless we want to
+/// highlight that we are referring to a specific part of a datamodel.
 class DatamodelRegistry {
 public:
   /// Get the registry
@@ -70,59 +64,57 @@ class DatamodelRegistry {
   /// Dedicated index value for error checking, used to default init the generated RegistryIndex
   static constexpr size_t NoDefinitionAvailable = -2;
 
-  /**
-   * Get the definition (in JSON format) of the datamodel with the given
-   * edmName.
-   *
-   * If no datamodel with the given name can be found, an empty datamodel
-   * definition, i.e. an empty JSON object ("{}"), is returned.
-   *
-   * @param name The name of the datamodel
-   */
+  /// Get the definition (in JSON format) of the datamodel with the given
+  /// edmName.
+  ///
+  /// If no datamodel with the given name can be found, an empty datamodel
+  /// definition, i.e. an empty JSON object ("{}"), is returned.
+  ///
+  /// @param name The name of the datamodel
+  ///
+  /// @returns The high level definition of the datamodel in JSON format
   const std::string_view getDatamodelDefinition(std::string_view name) const;
 
-  /**
-   * Get the definition (in JSON format) of the datamodel with the given index.
-   *
-   * If no datamodel is found under the given index, an empty datamodel
-   * definition, i.e. an empty JSON object ("{}"), is returned.
-   *
-   * @param index The datamodel definition index that can be obtained from each
-   *              collection
-   */
+  /// Get the definition (in JSON format) of the datamodel with the given
+  /// index.
+  ///
+  /// If no datamodel is found under the given index, an empty datamodel
+  /// definition, i.e. an empty JSON object ("{}"), is returned.
+  ///
+  /// @param index The datamodel definition index that can be obtained from each
+  ///              collection
+  ///
+  /// @returns The high level definition of the datamodel in JSON format
   const std::string_view getDatamodelDefinition(size_t index) const;
 
-  /**
-   * Get the name of the datamodel that is stored under the given index.
-   *
-   * If no datamodel is found under the given index, an empty string is returned
-   *
-   * @param index The datamodel definition index that can be obtained from each
-   *              collection
-   */
+  /// Get the name of the datamodel that is stored under the given index.
+  ///
+  /// If no datamodel is found under the given index, an empty string is returned
+  ///
+  /// @param index The datamodel definition index that can be obtained from each
+  ///              collection
+  ///
+  /// @returns The name of the datamodel
   const std::string& getDatamodelName(size_t index) const;
 
-  /**
-   * Register a datamodel return the index in the registry.
-   *
-   * This is the hook that is called during dynamic loading of an EDM to
-   * register information for this EDM. If an EDM has already been registered
-   * under this name, than the index to the existing EDM in the registry will be
-   * returned.
-   *
-   * @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
-   * datatypes that are defined for this EDM
-   *
-   */
+  /// Register a datamodel and return its index in the registry.
+  ///
+  /// This is the hook that is called during dynamic loading of an EDM to
+  /// register information for this EDM. If an EDM has already been registered
+  /// under this name, than the index to the existing EDM in the registry will be
+  /// returned.
+  ///
+  /// @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
+  /// datatypes that are defined for this EDM
+  ///
+  /// @returns The index of this datamodel in the registry
   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 of a datatype
   RelationNames getRelationNames(std::string_view typeName) const;
 
 private: