docs(ridfire)

Added more documentation, also moved all engine code into
gridfire::engine namespace to be more in line with other parts of teh
code base

src/include/gridfire/policy/policy_logical.h

@@ -22,30 +22,211 @@ namespace gridfire::policy {
      */
     class MultiReactionChainPolicy : public ReactionChainPolicy {
     public:
+        /**
+         * @brief Constructs a MultiReactionChainPolicy from a vector of ReactionChainPolicy instances.
+         *
+         * The provided chain policies are moved into the new MultiReactionChainPolicy instance.
+         *
+         * @param chain_policies vector of unique_ptr to ReactionChainPolicy instances.
+         *
+         * @par Example
+         * @code
+         * std::vector<std::unique_ptr<ReactionChainPolicy>> chains;
+         * chains.push_back(std::make_unique<ProtonProtonChainPolicy>());
+         * chains.push_back(std::make_unique<CNOChainPolicy>());
+         * MultiReactionChainPolicy multi(std::move(chains));
+         * @endcode
+         */
         explicit MultiReactionChainPolicy(std::vector<std::unique_ptr<ReactionChainPolicy>>&& chain_policies);
 
+        /**
+         * @brief Returns the vector of child ReactionChainPolicy instances.
+         *
+         * @return const std::vector<std::unique_ptr<ReactionChainPolicy>>& reference to the child chain policies.
+         *
+         * @par Example
+         * @code
+         * const auto &chains = multi.get_chain_policies();
+         * for (const auto &ch : chains) { std::cout << ch->get_reactions().size() << " reactions\n"; }
+         * @endcode
+         */
         [[nodiscard]] const std::vector<std::unique_ptr<ReactionChainPolicy>>& get_chain_policies() const;
 
+        /**
+         * @brief Returns the combined ReactionSet of all child chain policies.
+         *
+         * @return const reaction::ReactionSet& reference to the combined reactions.
+         *
+         * @par Example
+         * @code
+         * const auto &reactions = multi.get_reactions();
+         * std::cout << "Multi chain contains " << reactions.size() << " reactions\n";
+         * @endcode
+         */
         [[nodiscard]] const reaction::ReactionSet& get_reactions() const override;
 
+        /**
+         * @brief Checks if the MultiReactionChainPolicy contains a reaction by ID
+         *
+         * @param id the reaction ID to check for.
+         * @return true if the reaction ID is present in the combined ReactionSet, false otherwise.
+         *
+         * @par Example
+         * @code
+         * bool has_pp = multi.contains("p(p,e+)d");
+         * @endcode
+         */
         [[nodiscard]] bool contains(const std::string &id) const override;
+
+        /**
+         * @brief Checks if the MultiReactionChainPolicy contains a specific reaction.
+         *
+         * @param reaction the Reaction to check for.
+         * @return true if the reaction is present in the combined ReactionSet, false otherwise.
+         *
+         * @par Example
+         * @code
+         * reaction::Reaction r = ...; // obtain a Reaction instance
+         * bool has_reaction = multi.contains(r);
+         * @endcode
+         */
         [[nodiscard]] bool contains(const reaction::Reaction &reaction) const override;
 
+        /**
+         * @brief Creates a deep copy of the MultiReactionChainPolicy.
+         *
+         * @return std::unique_ptr<ReactionChainPolicy> unique pointer to the cloned instance.
+         *
+         * @par Example
+         * @code
+         * std::unique_ptr<ReactionChainPolicy> clone = multi.clone();
+         * @endcode
+         */
         [[nodiscard]] std::unique_ptr<ReactionChainPolicy> clone() const override;
+
+        /**
+         * @brief Returns the name of the MultiReactionChainPolicy.
+         *
+         * @return std::string the name of the policy.
+         *
+         * @par Example
+         * @code
+         * std::string n = multi.name();
+         * std::cout << "Using policy: " << n << std::endl;
+         * @endcode
+         */
         [[nodiscard]] std::string name() const override;
+
+        /**
+         * @brief Computes a hash value for the MultiReactionChainPolicy.
+         *
+         * @param seed the seed value for the hash computation.
+         * @return uint64_t the computed hash value.
+         *
+         * @par Example
+         * @code
+         * uint64_t h = multi.hash(0);
+         * std::cout << "Policy hash: " << h << std::endl;
+         * @endcode
+         */
         [[nodiscard]] uint64_t hash(uint64_t seed) const override;
 
+        /**
+         * @brief Equality comparison operator.
+         *
+         * @param other the other ReactionChainPolicy to compare against.
+         * @return true if the policies are equal, false otherwise.
+         *
+         * @par Example
+         * @code
+         * bool equal = (multi1 == multi2);
+         * @endcode
+         */
         [[nodiscard]] bool operator==(const ReactionChainPolicy& other) const override;
+
+        /**
+         * @brief Inequality comparison operator.
+         *
+         * @param other the other ReactionChainPolicy to compare against.
+         * @return true if the policies are not equal, false otherwise.
+         *
+         * @par Example
+         * @code
+         * bool not_equal = (multi1 != multi2);
+         * @endcode
+         */
         [[nodiscard]] bool operator!=(const ReactionChainPolicy& other) const override;
 
+        /**
+         * @brief Returns the number of child ReactionChainPolicy instances.
+         *
+         * @return size_t the number of child chain policies.
+         *
+         * @par Example
+         * @code
+         * size_t n = multi.size();
+         * std::cout << "Multi chain has " << n << " child policies\n";
+         * @endcode
+         */
         [[nodiscard]] size_t size() const;
 
+        /**
+         * @brief Returns iterator to the beginning of the child ReactionChainPolicy instances.
+         *
+         * @return iterator to the beginning.
+         *
+         * @par Example
+         * @code
+         * for (auto it = multi.begin(); it != multi.end(); ++it) {
+         *     std::cout << (*it)->name() << std::endl;
+         * }
+         * @endcode
+         */
         auto begin() { return m_chain_policies.begin(); }
+
+        /**
+         * @brief Returns const iterator to the beginning of the child ReactionChainPolicy instances.
+         *
+         * @return const iterator to the beginning.
+         *
+         * @par Example
+         * @code
+         * for (auto it = multi.begin(); it != multi.end(); ++it) {
+         *     std::cout << (*it)->name() << std::endl;
+         * }
+         * @endcode
+         */
         [[nodiscard]] auto begin() const { return m_chain_policies.cbegin(); }
+
+        /**
+         * @brief Returns iterator to the end of the child ReactionChainPolicy instances.
+         *
+         * @return iterator to the end.
+         *
+         * @par Example
+         * @code
+         * for (auto it = multi.begin(); it != multi.end(); ++it) {
+         *     std::cout << (*it)->name() << std::endl;
+         * }
+         * @endcode
+         */
         auto end() { return m_chain_policies.end(); }
+
+        /**
+         * @brief Returns const iterator to the end of the child ReactionChainPolicy instances.
+         *
+         * @return const iterator to the end.
+         *
+         * @par Example
+         * @code
+         * for (auto it = multi.begin(); it != multi.end(); ++it) {
+         *     std::cout << (*it)->name() << std::endl;
+         * }
+         * @endcode
+         */
         [[nodiscard]] auto end() const { return m_chain_policies.cend(); }
     protected:
-        std::vector<std::unique_ptr<ReactionChainPolicy>> m_chain_policies{};
-        reaction::ReactionSet m_reactions;
+        std::vector<std::unique_ptr<ReactionChainPolicy>> m_chain_policies{}; ///< Child chain policies
+        reaction::ReactionSet m_reactions; ///< Combined reactions from all child policies
     };
 }