Add some docstrings

Author: denialhaag

mlir/include/mlir/Conversion/JeffToQC/JeffToQC.td

@@ -9,7 +9,7 @@
 include "mlir/Pass/PassBase.td"
 
 def JeffToQC : Pass<"jeff-to-qc"> {
-  let summary = "TODO";
+  let summary = "Convert Jeff operations to QC operations";
 
   let description = [{
       TODO

mlir/include/mlir/Conversion/QCToJeff/QCToJeff.td

@@ -9,7 +9,7 @@
 include "mlir/Pass/PassBase.td"
 
 def QCToJeff : Pass<"qc-to-jeff"> {
-  let summary = "TODO";
+  let summary = "Convert QC operations to Jeff operations";
 
   let description = [{
       TODO

mlir/include/mlir/Dialect/QC/IR/QCOps.td

@@ -943,7 +943,7 @@ def CtrlOp : QCOp<"ctrl",
         ```mlir
         qc.ctrl(%q0) {
           qc.x %q1 : !qc.qubit
-        }
+        } : !qc.qubit
         ```
     }];
 

mlir/lib/Conversion/JeffToQC/JeffToQC.cpp

@@ -30,6 +30,17 @@ using namespace qc;
 #define GEN_PASS_DEF_JEFFTOQC
 #include "mlir/Conversion/JeffToQC/JeffToQC.h.inc"
 
+/**
+ * @brief Converts a one-target, zero-parameter Jeff operation to QC
+ *
+ * @tparam QCOpType The operation type of the QC operation
+ * @tparam JeffOpType The operation type of the Jeff operation
+ * @tparam JeffOpAdaptorType The OpAdaptor type of the Jeff operation
+ * @param op The Jeff operation instance to convert
+ * @param adaptor The OpAdaptor of the Jeff operation
+ * @param rewriter The pattern rewriter
+ * @return LogicalResult Success or failure of the conversion
+ */
 template <typename QCOpType, typename JeffOpType, typename JeffOpAdaptorType>
 static LogicalResult
 convertOneTargetZeroParameter(JeffOpType& op, JeffOpAdaptorType& adaptor,
@@ -59,6 +70,17 @@ convertOneTargetZeroParameter(JeffOpType& op, JeffOpAdaptorType& adaptor,
   return success();
 }
 
+/**
+ * @brief Converts a one-target, one-parameter Jeff operation to QC
+ *
+ * @tparam QCOpType The operation type of the QC operation
+ * @tparam JeffOpType The operation type of the Jeff operation
+ * @tparam JeffOpAdaptorType The OpAdaptor type of the Jeff operation
+ * @param op The Jeff operation instance to convert
+ * @param adaptor The OpAdaptor of the Jeff operation
+ * @param rewriter The pattern rewriter
+ * @return LogicalResult Success or failure of the conversion
+ */
 template <typename QCOpType, typename JeffOpType, typename JeffOpAdaptorType>
 static LogicalResult
 convertOneTargetOneParameter(JeffOpType& op, JeffOpAdaptorType& adaptor,
@@ -88,37 +110,18 @@ convertOneTargetOneParameter(JeffOpType& op, JeffOpAdaptorType& adaptor,
   return success();
 }
 
-template <typename QCOpType, typename JeffOpType, typename JeffOpAdaptorType>
-static LogicalResult
-convertTwoTargetZeroParameter(JeffOpType& op, JeffOpAdaptorType& adaptor,
-                              ConversionPatternRewriter& rewriter) {
-  if (op.getPower() != 1) {
-    return rewriter.notifyMatchFailure(
-        op, "Operations with power != 1 are not yet supported");
-  }
-
-  auto target1 = adaptor.getInQubitOne();
-  auto target2 = adaptor.getInQubitTwo();
-
-  if (op.getNumCtrls() != 0) {
-    auto controls = adaptor.getInCtrlQubits();
-    rewriter.create<qc::CtrlOp>(op.getLoc(), controls, [&] {
-      rewriter.create<QCOpType>(op.getLoc(), target1, target2);
-    });
-    SmallVector<Value> operands;
-    operands.reserve(2 + controls.size());
-    operands.push_back(target1);
-    operands.push_back(target2);
-    operands.append(controls.begin(), controls.end());
-    rewriter.replaceOp(op, operands);
-  } else {
-    rewriter.create<QCOpType>(op.getLoc(), target1, target2);
-    rewriter.replaceOp(op, {target1, target2});
-  }
-
-  return success();
-}
-
+/**
+ * @brief Converts jeff.qubit_alloc to qc.alloc
+ *
+ * @par Example:
+ * ```mlir
+ * %q = jeff.qubit_alloc : !jeff.qubit
+ * ```
+ * is converted to
+ * ```mlir
+ * %q = qc.alloc : !qc.qubit
+ * ```
+ */
 struct ConvertJeffQubitAllocOpToQC final
     : OpConversionPattern<jeff::QubitAllocOp> {
   using OpConversionPattern::OpConversionPattern;
@@ -131,6 +134,18 @@ struct ConvertJeffQubitAllocOpToQC final
   }
 };
 
+/**
+ * @brief Converts jeff.qubit_free to qc.dealloc
+ *
+ * @par Example:
+ * ```mlir
+ * jeff.qubit_free %q : !jeff.qubit
+ * ```
+ * is converted to
+ * ```mlir
+ * qc.dealloc %q : !qc.qubit
+ * ```
+ */
 struct ConvertJeffQubitFreeOpToQC final
     : OpConversionPattern<jeff::QubitFreeOp> {
   using OpConversionPattern::OpConversionPattern;
@@ -144,6 +159,18 @@ struct ConvertJeffQubitFreeOpToQC final
   }
 };
 
+/**
+ * @brief Converts jeff.qubit_measure_nd to qc.measure
+ *
+ * @par Example:
+ * ```mlir
+ * %result, %q_out = jeff.qubit_measure_nd %q_in : i1, !jeff.qubit
+ * ```
+ * is converted to
+ * ```mlir
+ * %result = qc.measure %q : i1
+ * ```
+ */
 struct ConvertJeffQubitMeasureNDOpToQC final
     : OpConversionPattern<jeff::QubitMeasureNDOp> {
   using OpConversionPattern::OpConversionPattern;
@@ -158,6 +185,18 @@ struct ConvertJeffQubitMeasureNDOpToQC final
   }
 };
 
+/**
+ * @brief Converts jeff.reset to qc.qubit_reset
+ *
+ * @par Example:
+ * ```mlir
+ * %q_out = jeff.qubit_reset %q_in : !jeff.qubit
+ * ```
+ * is converted to
+ * ```mlir
+ * %result = qc.reset %q : !qc.qubit
+ * ```
+ */
 struct ConvertJeffQubitResetOpToQC final
     : OpConversionPattern<jeff::QubitResetOp> {
   using OpConversionPattern::OpConversionPattern;
@@ -172,6 +211,18 @@ struct ConvertJeffQubitResetOpToQC final
   }
 };
 
+/**
+ * @brief Converts jeff.gphase to qc.gphase
+ *
+ * @par Example:
+ * ```mlir
+ * jeff.gphase(%theta) {is_adjoint = false, num_ctrls = 0 : i8, power = 1 : i8}
+ * ```
+ * is converted to
+ * ```mlir
+ * qc.gphase(%theta)
+ * ```
+ */
 struct ConvertJeffGPhaseOpToQC final : OpConversionPattern<jeff::GPhaseOp> {
   using OpConversionPattern::OpConversionPattern;
 
@@ -250,8 +301,19 @@ DEFINE_ONE_TARGET_ONE_PARAMETER(R1Op, POp)
 
 #undef DEFINE_ONE_TARGET_ONE_PARAMETER
 
-// OneTargetOneParameter
-
+/**
+ * @brief Converts jeff.u to qc.u
+ *
+ * @par Example:
+ * ```mlir
+ * %q_out = jeff.u(%theta, %phi, %lambda) {is_adjoint = false, num_ctrls = 0 :
+ * i8, power = 1 : i8} %q_in : !jeff.qubit
+ * ```
+ * is converted to
+ * ```mlir
+ * qc.u(%theta, %phi, %lambda) %q : !qc.qubit
+ * ```
+ */
 struct ConvertJeffUOpToQC final : OpConversionPattern<jeff::UOp> {
   using OpConversionPattern::OpConversionPattern;
 
@@ -286,25 +348,59 @@ struct ConvertJeffUOpToQC final : OpConversionPattern<jeff::UOp> {
   }
 };
 
-// TwoTargetZeroParameter
+/**
+ * @brief Converts jeff.swap to qc.swap
+ *
+ * @par Example:
+ * ```mlir
+ * %q0_out, %q1_out = jeff.swap {is_adjoint = false, num_ctrls = 0 : i8, power =
+ * 1 : i8} %q0_in %q1_in : !jeff.qubit !jeff.qubit
+ * ```
+ * is converted to
+ * ```mlir
+ * qc.swap %q0, %q1 : !qc.qubit, !qc.qubit
+ * ```
+ */
+struct ConvertJeffSwapOpToQC final : OpConversionPattern<jeff::SwapOp> {
+  using OpConversionPattern::OpConversionPattern;
 
-#define DEFINE_TWO_TARGET_ZERO_PARAMETER(OP_CLASS_JEFF, OP_CLASS_QC)           \
-  struct ConvertJeff##OP_CLASS_JEFF##ToQC final                                \
-      : OpConversionPattern<jeff::OP_CLASS_JEFF> {                             \
-    using OpConversionPattern::OpConversionPattern;                            \
-                                                                               \
-    LogicalResult                                                              \
-    matchAndRewrite(jeff::OP_CLASS_JEFF op, OpAdaptor adaptor,                 \
-                    ConversionPatternRewriter& rewriter) const override {      \
-      return convertTwoTargetZeroParameter<qc::OP_CLASS_QC>(op, adaptor,       \
-                                                            rewriter);         \
-    }                                                                          \
-  };
+  LogicalResult
+  matchAndRewrite(jeff::SwapOp op, OpAdaptor adaptor,
+                  ConversionPatternRewriter& rewriter) const override {
+    if (op.getPower() != 1) {
+      return rewriter.notifyMatchFailure(
+          op, "Operations with power != 1 are not yet supported");
+    }
 
-DEFINE_TWO_TARGET_ZERO_PARAMETER(SwapOp, SWAPOp)
+    auto target1 = adaptor.getInQubitOne();
+    auto target2 = adaptor.getInQubitTwo();
 
-#undef DEFINE_TWO_TARGET_ZERO_PARAMETER
+    if (op.getNumCtrls() != 0) {
+      auto controls = adaptor.getInCtrlQubits();
+      rewriter.create<qc::CtrlOp>(op.getLoc(), controls, [&] {
+        rewriter.create<qc::SWAPOp>(op.getLoc(), target1, target2);
+      });
+      SmallVector<Value> operands;
+      operands.reserve(2 + controls.size());
+      operands.push_back(target1);
+      operands.push_back(target2);
+      operands.append(controls.begin(), controls.end());
+      rewriter.replaceOp(op, operands);
+    } else {
+      rewriter.create<qc::SWAPOp>(op.getLoc(), target1, target2);
+      rewriter.replaceOp(op, {target1, target2});
+    }
+
+    return success();
+  }
+};
 
+/**
+ * @brief Type converter for Jeff-to-QC conversion
+ *
+ * @details
+ * Converts `!jeff.qubit` to `!qc.qubit`.
+ */
 class JeffToQCTypeConverter final : public TypeConverter {
 public:
   explicit JeffToQCTypeConverter(MLIRContext* ctx) {
@@ -317,6 +413,12 @@ class JeffToQCTypeConverter final : public TypeConverter {
   }
 };
 
+/**
+ * @brief Pass for converting Jeff operations to QC operations
+ *
+ * @details
+ * TODO
+ */
 struct JeffToQC final : impl::JeffToQCBase<JeffToQC> {
   using JeffToQCBase::JeffToQCBase;
 

mlir/lib/Conversion/QCOToQC/QCOToQC.cpp

@@ -761,7 +761,7 @@ struct ConvertQCOBarrierOp final : OpConversionPattern<qco::BarrierOp> {
  * ```mlir
  * qc.ctrl(%q0) {
  *   qc.x %q1 : !qc.qubit
- * }
+ * } : !qc.qubit
  * ```
  */
 struct ConvertQCOCtrlOp final : OpConversionPattern<qco::CtrlOp> {