refactor(assertion-tools): 📝 Add docstrings to all new non-test funct…

…ions

include/backend/dd/DDSimDiagnostics.hpp

@@ -16,13 +16,37 @@
 #include <set>
 #include <vector>
 
+/**
+ * @brief Represents an equality assertion that should be inserted into the
+ * program.
+ */
 struct InsertEqualityAssertion {
+
+  /**
+   * @brief The index of the instruction where the assertion should be inserted.
+   */
   size_t instructionIndex;
+
+  /**
+   * @brief The amplitudes that the assertion should check for equality.
+   */
   std::vector<Complex> amplitudes;
+
+  /**
+   * @brief The similarity threshold for the assertion.
+   */
   double similarity;
+
+  /**
+   * @brief The target qubits of the assertion.
+   */
   std::vector<std::string> targets;
 
-  // Define operator== to support equality comparisons
+  /**
+   * @brief Check whether two InsertEqualityAssertion instances are equal.
+   * @param other The other InsertEqualityAssertion instance to compare with.
+   * @return True if the instances are equal, false otherwise.
+   */
   bool operator==(const InsertEqualityAssertion& other) const {
     if (instructionIndex != other.instructionIndex ||
         targets != other.targets) {
@@ -78,9 +102,22 @@ struct DDDiagnostics {
    */
   std::map<size_t, std::set<std::vector<size_t>>> actualQubits;
 
+  /**
+   * @brief Assertions that have been identified to be moved in the program.
+   */
   std::vector<std::pair<size_t, size_t>> assertionsToMove;
+
+  /**
+   * @brief The entanglement assertions that have been identified to be added to
+   * the program.
+   */
   std::map<size_t, std::set<std::pair<std::set<std::string>, size_t>>>
       assertionsEntToInsert;
+
+  /**
+   * @brief The equality assertions that have been identified to be added to the
+   * program.
+   */
   std::map<size_t, std::vector<InsertEqualityAssertion>> assertionsEqToInsert;
 };
 

include/common/parsing/AssertionTools.hpp

@@ -5,15 +5,40 @@
 
 #include <memory>
 
+/**
+ * @brief Define a general commutation rule.
+ *
+ * @param name The name of the commutation rule.
+ * @param expression The expression that performs the check.
+ */
 #define COMMUTATION_RULE_GENERAL(name, expression)                             \
   COMMUTATION_RULE_TEMPLATE(Assertion, name, expression)
 
+/**
+ * @brief Define a commutation rule for entanglement assertions.
+ *
+ * @param name The name of the commutation rule.
+ * @param expression The expression that performs the check.
+ */
 #define COMMUTATION_RULE_ENT(name, expression)                                 \
   COMMUTATION_RULE_TEMPLATE(EntanglementAssertion, name, expression)
 
+/**
+ * @brief Define a commutation rule for superposition assertions.
+ *
+ * @param name The name of the commutation rule.
+ * @param expression The expression that performs the check.
+ */
 #define COMMUTATION_RULE_SUP(name, expression)                                 \
   COMMUTATION_RULE_TEMPLATE(SuperpositionAssertion, name, expression)
 
+/**
+ * @brief Define a template for commutation rules.
+ *
+ * @param type The type of assertion to check.
+ * @param name The name of the commutation rule.
+ * @param expression The expression that performs the check.
+ */
 #define COMMUTATION_RULE_TEMPLATE(type, name, expression)                      \
   const auto name = [](const type* assertion,                                  \
                        const std::string& instructionName,                     \
@@ -24,11 +49,32 @@
     return expression;                                                         \
   }
 
+/**
+ * @brief The possible results of a commutation check.
+ *
+ * Can be either `Commutes`, `DoesNotCommute`, or `Unknown`.
+ */
 enum class CommutationResult {
+  /**
+   * @brief Indicates that the instructions commute with certainty.
+   */
   Commutes,
+  /**
+   * @brief Indicates that the instructions do not commute with certainty.
+   */
   DoesNotCommute,
+  /**
+   * @brief Indicates that it cannot be said with certainty whether the
+   * instructions commute or not.
+   */
   Unknown,
 };
 
+/**
+ * @brief Check if an assertion commutes with an instruction.
+ * @param assertion The assertion to check.
+ * @param instruction The instruction to check.
+ * @return True if the assertion commutes with the instruction, false otherwise.
+ */
 bool doesCommute(const std::unique_ptr<Assertion>& assertion,
                  const Instruction& instruction);

include/frontend/cli/CliFrontEnd.hpp

@@ -55,5 +55,10 @@ class CliFrontEnd {
    */
   void initCode(const char* code);
 
+  /**
+   * @brief Output a new code with updated assertions based on the assertion
+   * refinement rules.
+   * @param state The simulation state.
+   */
   void suggestUpdatedAssertions(SimulationState* state);
 };

src/backend/dd/DDSimDiagnostics.cpp

@@ -678,6 +678,12 @@ findUniquePath(const std::set<std::tuple<size_t, size_t, size_t>>& graph,
   return path;
 }
 
+/**
+ * @brief Suggest new assertions based on a failed entanglement assertion.
+ * @param self The diagnostics instance.
+ * @param instructionIndex The index of the assertion that failed.
+ * @param assertion The assertion that failed.
+ */
 void suggestBasedOnFailedEntanglementAssertion(
     DDDiagnostics* self, size_t instructionIndex,
     const EntanglementAssertion* assertion) {
@@ -753,6 +759,13 @@ void suggestBasedOnFailedEntanglementAssertion(
   }
 }
 
+/**
+ * @brief Suggest new assertions based on the splitting of an equality
+ * assertion.
+ * @param self The diagnostics instance.
+ * @param instructionIndex The index of the assertion to split.
+ * @param assertion The assertion to split.
+ */
 void suggestSplitEqualityAssertion(
     DDDiagnostics* self, size_t instructionIndex,
     const StatevectorEqualityAssertion* assertion) {

src/common/parsing/AssertionTools.cpp

@@ -68,6 +68,13 @@ static const std::vector<std::function<CommutationResult(
         OTHER_1Q_GATE_INVARIANTS,
 };
 
+/**
+ * @brief Check if an entanglement assertion commutes with an instruction.
+ * @param assertion The assertion to check.
+ * @param instructionName The name of the instruction to check.
+ * @param targets The targets of the instruction.
+ * @return True if the assertion commutes with the instruction, false otherwise.
+ */
 bool doesCommuteEnt(const EntanglementAssertion* assertion,
                     const std::string& instructionName,
                     const std::vector<std::string>& targets) {
@@ -80,6 +87,13 @@ bool doesCommuteEnt(const EntanglementAssertion* assertion,
   return false;
 }
 
+/**
+ * @brief Check if a superposition assertion commutes with an instruction.
+ * @param assertion The assertion to check.
+ * @param instructionName The name of the instruction to check.
+ * @param targets The targets of the instruction.
+ * @return True if the assertion commutes with the instruction, false otherwise.
+ */
 bool doesCommuteSup(const SuperpositionAssertion* assertion,
                     const std::string& instructionName,
                     const std::vector<std::string>& targets) {
@@ -92,6 +106,12 @@ bool doesCommuteSup(const SuperpositionAssertion* assertion,
   return false;
 }
 
+/**
+ * @brief Check if a general assertion commutes with an instruction.
+ * @param assertion The assertion to check.
+ * @param instruction The instruction to check in string form.
+ * @return True if the assertion commutes with the instruction, false otherwise.
+ */
 bool doesCommute(const std::unique_ptr<Assertion>& assertion,
                  const std::string& instruction) {
   const auto targets = parseParameters(instruction);