Add docstring to the new CircuitData constructor method

crates/circuit/src/circuit_data.rs

@@ -166,6 +166,33 @@ impl CircuitData {
         Ok(res)
     }
 
+    /// A constructor for CircuitData from an iterator of PackedInstruction objects
+    ///
+    /// This is tpically useful when iterating over a CircuitData or DAGCircuit
+    /// to construct a new CircuitData from the iterator of PackedInstructions. As
+    /// such it requires that you have `BitData` and `Interner` objects to run. If
+    /// you just wish to build a circuit data from an iterator of instructions
+    /// the `from_packed_operations` or `from_standard_gates` constructor methods
+    /// are a better choice
+    ///
+    /// # Args
+    ///
+    /// * py: A GIL handle this is needed to instantiate Qubits in Python space
+    /// * qubits: The BitData to use for the new circuit's qubits
+    /// * clbits: The BitData to use for the new circuit's clbits
+    /// * qargs_interner: The interner for Qubit objects in the circuit. This must
+    ///     contain all the Interned<Qubit> indices stored in the
+    ///     PackedInstructions from `instructions`
+    /// * cargs_interner: The interner for Clbit objects in the circuit. This must
+    ///     contain all the Interned<Clbit> indices stored in the
+    ///     PackedInstructions from `instructions`
+    /// * Instructions: An iterator with items of type: `PyResult<PackedInstruction>`
+    ///     that contais the instructions to insert in iterator order to the new
+    ///     CircuitData. This returns a `PyResult` to facilitate the case where
+    ///     you need to make a python copy (such as with `PackedOperation::py_deepcopy()`)
+    ///     of the operation while iterating for constructing the new `CircuitData`. An
+    ///     example of this use case is in `qiskit_circuit::converters::dag_to_circuit`.
+    /// * global_phase: The global phase value to use for the new circuit.
     pub fn from_packed_instructions<I>(
         py: Python,
         qubits: BitData<Qubit>,