#216 Add comments

sources/Algo/include/Algo.h

@@ -863,14 +863,22 @@ class DynModelAlgorithm : public NodeAlgorithm {
   const inputs::DynamicDataBaseManager& manager_;  ///< dynamic database config manager
 };
 
+/// @brief Shunts definition for a voltage level
 struct VLShuntsDefinition {
+  /// @brief Hash for shunts definition
   struct ShuntHash {
+    /**
+     * @brief Retrieve the hash value
+     *
+     * @param shunt the shunt to hash
+     * @return the hash value
+     */
     size_t operator()(const inputs::Shunt& shunt) const noexcept;
   };
-  using ShuntsSet = std::unordered_set<inputs::Shunt, ShuntHash>;
+  using ShuntsSet = std::unordered_set<inputs::Shunt, ShuntHash>;  ///< Alias for set of shunts
 
-  ShuntsSet shunts;
-  bool dynamicModelAssociated = false;
+  ShuntsSet shunts;                     ///< Set of shunts for current voltage level
+  bool dynamicModelAssociated = false;  ///< determines if the current voltage level is associated with a dynamic model
 };
 
 /**
@@ -888,6 +896,7 @@ class ShuntDefinitionAlgorithm : public NodeAlgorithm {
   /**
    * @brief Constructor
    * @param shuntCounterDefs the counter definitions to update
+   * @param manager dynamic data base manager
    */
   ShuntDefinitionAlgorithm(ShuntDefinitions& shuntCounterDefs, const inputs::DynamicDataBaseManager& manager);
 
@@ -901,8 +910,8 @@ class ShuntDefinitionAlgorithm : public NodeAlgorithm {
   void operator()(const NodePtr& node);
 
  private:
-  ShuntDefinitions& shuntDefs_;  ///< the counter definitions to update
-  std::unordered_set<inputs::VoltageLevel::VoltageLevelId> voltageLevelsWithAssociation_;
+  ShuntDefinitions& shuntDefs_;                                                            ///< the counter definitions to update
+  std::unordered_set<inputs::VoltageLevel::VoltageLevelId> voltageLevelsWithAssociation_;  ///< dynamic data base manager
 };
 
 /**

sources/Inputs/include/Node.h

@@ -141,12 +141,16 @@ class Tfo {
 /// @brief Topological shunt
 struct Shunt {
   using ShuntId = std::string;  ///< alias for shunt id
-  using BusId = std::string;
+  using BusId = std::string;    ///< Alias for bus id regulated by the shunt
 
   /**
-   * @brief Constructor
+   * @brief Construct a new Shunt
    *
    * @param id the shunt id
+   * @param busId the regulated bus of the shunt
+   * @param targetV the target V of the shunt
+   * @param voltageRegulationOn whether voltage regulation is enabled for the shunt
+   * @param bs the vector of the B values for the shunt
    */
   Shunt(const ShuntId& id, const BusId& busId, double targetV, bool voltageRegulationOn, const std::vector<double>& bs) :
       id(id),
@@ -155,15 +159,23 @@ struct Shunt {
       voltageRegulationOn(voltageRegulationOn),
       bSections(bs) {}
 
+  /**
+   * @brief Equality operator
+   *
+   * comparing the ids
+   *
+   * @param other the shunt to compare to
+   * @return @b true if the shunts are equal, @b false if not
+   */
   bool operator==(const Shunt& other) const {
     return id == other.id;
   }
 
-  const ShuntId id;  ///< Shunt id
-  const BusId busId;
-  const double targetV;
-  const bool voltageRegulationOn;
-  const std::vector<double> bSections;
+  const ShuntId id;                     ///< Shunt id
+  const BusId busId;                    ///< the regulated bus of the shunt
+  const double targetV;                 ///< the target V of the shunt
+  const bool voltageRegulationOn;       ///< whether voltage regulation is enabled for the shunt
+  const std::vector<double> bSections;  ///< the vector of the B values for the shunt
 };
 
 /**

sources/Outputs/include/Constants.h

@@ -82,6 +82,12 @@ const std::string xmlEncoding{"UTF-8"};
 
 constexpr double powerValueMax = std::numeric_limits<double>::max();  ///< Maximum value for powers, meaning infinite
 
+/**
+ * @brief Compute the list of shunts, sorting by regulated bus id
+ *
+ * @param shuntDefinitions the shund definitions to use
+ * @return the sorted list of shunts
+ */
 std::unordered_map<inputs::Shunt::BusId, std::vector<std::reference_wrapper<const inputs::Shunt>>>
 computeShuntsByIds(const algo::ShuntDefinitions& shuntDefinitions);
 

sources/Outputs/include/Dyd.h

@@ -104,6 +104,7 @@ class Dyd {
      * @param dynamicDataBaseManager the database manager to use
      * @param models the list of dynamic models to use
      * @param svarcsDefinitions the SVarC definitions to use
+     * @param shuntsDefinitions the shuntsDefinitions to use
      */
     DydDefinition(const std::string& base, const std::string& filepath, const std::vector<algo::GeneratorDefinition>& gens,
                   const std::vector<algo::LoadDefinition>& loaddefs, const std::shared_ptr<inputs::Node>& slacknode,
@@ -132,7 +133,7 @@ class Dyd {
     const inputs::DynamicDataBaseManager& dynamicDataBaseManager;                ///< dynamic database manager
     const algo::DynamicModelDefinitions& dynamicModelsDefinitions;               ///< the list of dynamic models to export
     const algo::StaticVarCompensatorDefinitions& svarcsDefinitions;              ///< the SVarC definitions to use
-    const algo::ShuntDefinitions& shuntsDefinitions;
+    const algo::ShuntDefinitions& shuntsDefinitions;                             ///< the shuntsDefinitions to use
   };
 
   /**
@@ -188,6 +189,13 @@ class Dyd {
    */
   static boost::shared_ptr<dynamicdata::BlackBoxModel> writeHvdcLine(const algo::HVDCDefinition& hvdcLine, const std::string& basename);
 
+  /**
+   * @brief Write the black box model for shunt regulation
+   *
+   * @param busId the bus id to use
+   * @param basename the basename of the writer
+   * @return the model of the shunt regulation
+   */
   static boost::shared_ptr<dynamicdata::BlackBoxModel> writeShuntRegulation(const inputs::Shunt::BusId& busId, const std::string& basename);
 
   /**

sources/Outputs/include/Par.h

@@ -164,6 +164,13 @@ class Par {
   static boost::shared_ptr<parameters::ParametersSet> writeHdvcLine(const algo::HVDCDefinition& hvdcLine, const std::string& basename,
                                                                     const boost::filesystem::path& dirname);
 
+  /**
+   * @brief Write the parameters for a shunt regulation set
+   *
+   * @param busId the bus id of the shunt regulation
+   * @param shunts the list of the shunts for the bus
+   * @return the parameter set of the shunt regulation
+   */
   static boost::shared_ptr<parameters::ParametersSet> writeShuntRegulation(const inputs::Shunt::BusId& busId,
                                                                            const std::vector<std::reference_wrapper<const dfl::inputs::Shunt>>& shunts);