Docstring updates

crates/accelerate/src/split_2q_unitaries.rs

@@ -26,6 +26,8 @@ use qiskit_circuit::Qubit;
 
 use crate::two_qubit_decompose::{Specialization, TwoQubitWeylDecomposition};
 
+/// Extracts the K1r and K1l gates from the decomposition
+/// and creates them as new 1-qubit unitary gates.
 fn create_k1_gates<'a>(
     decomp: &'a TwoQubitWeylDecomposition,
     py: Python<'a>,
@@ -43,6 +45,7 @@ fn create_k1_gates<'a>(
     Ok((k1r_gate, k1l_gate))
 }
 
+/// Creates a new instruction and adds it to the DAG.
 fn add_new_op(
     new_dag: &mut DAGCircuit,
     new_op: OperationFromPython,

qiskit/transpiler/passes/optimization/split_2q_unitaries.py

@@ -25,6 +25,10 @@ class Split2QUnitaries(TransformationPass):
     matrix is actually a product of 2 single qubit gates. In these cases the 2q gate can be
     simplified into two single qubit gates and this pass will perform this optimization and will
     replace the two qubit gate with two single qubit :class:`.UnitaryGate`.
+
+    If some of the gates can be viewed as a swap joined by the product of 2 single qubit gates,
+    the pass will recreate the DAG, permuting the swapped qubits similar
+    to how it's done in :class:`ElidePermutations`.
     """
 
     def __init__(self, fidelity: float = 1.0 - 1e-16):