extend the documentation for qiskit.circuit.QuantumCircuit.measure

qiskit/circuit/quantumcircuit.py

@@ -2265,17 +2265,96 @@ def reset(self, qubit: QubitSpecifier) -> InstructionSet:
         return self.append(Reset(), [qubit], [])
 
     def measure(self, qubit: QubitSpecifier, cbit: ClbitSpecifier) -> InstructionSet:
-        """Measure quantum bit into classical bit (tuples).
+        """Measure quantum bit (qubit) into classical bit (cbit).
 
-        Args:
-            qubit: qubit to measure.
-            cbit: classical bit to place the measurement in.
+        When a qubit is measured, its state collapses to a classical bit and copied to a
+        classical wire.
 
-        Returns:
-            qiskit.circuit.InstructionSet: handle to the added instructions.
+        In this example, a qubit is measured and the result of that measurement is stored in the
+        classical bit (usually expressed in diagrams as a double line):
 
-        Raises:
-            CircuitError: if arguments have bad format.
+        .. code-block::
+
+           from qiskit import QuantumCircuit
+           circuit = QuantumCircuit(1,1)
+           circuit.h(0)
+           circuit.measure(0, 0)
+           circuit.draw()
+
+
+        .. parsed-literal::
+
+                  ┌───┐┌─┐
+               q: ┤ H ├┤M├
+                  └───┘└╥┘
+             c: 1/══════╩═
+                        0
+
+        It is possible to call ``measure`` with lists of qubits and cbits of the same size:
+
+        .. code-block::
+
+           circuit = QuantumCircuit(2,2)
+           circuit.measure([0,1], [0,1])  # same as "circuit.measure(0,0); circuit.measure(1,1);"
+
+
+        .. parsed-literal::
+
+                  ┌─┐
+             q_0: ┤M├───
+                  └╥┘┌─┐
+             q_1: ─╫─┤M├
+                   ║ └╥┘
+             c: 2/═╩══╩═
+                   0  1
+
+        It is also possible to do a one-to-many readout:
+
+        .. code-block::
+
+           circuit = QuantumCircuit(2,2)
+           circuit.measure(0, [0,1])  # same as "circuit.measure(0,0); circuit.measure(0,1);"
+
+
+        .. parsed-literal::
+
+                  ┌─┐┌─┐
+             q_0: ┤M├┤M├
+                  └╥┘└╥┘
+             q_1: ─╫──╫─
+                   ║  ║
+             c: 2/═╩══╩═
+                   0  1
+
+        Instead of lists, you can use :class:`~qiskit.circuit.QuantumRegister` and
+        :class:`~qiskit.circuit.ClassicalRegister` under the same logic.
+
+        .. code-block::
+
+            from qiskit import QuantumCircuit, QuantumRegister, ClassicalRegister
+            qreg = QuantumRegister(1, "qreg")
+            creg = ClassicalRegister(2, "creg")
+            circuit = QuantumCircuit(qreg, creg)
+            circuit.measure(qreg, creg)
+
+
+        .. parsed-literal::
+
+                    ┌─┐┌─┐
+              qreg: ┤M├┤M├
+                    └╥┘└╥┘
+            creg: 2/═╩══╩═
+                     0  1
+
+         Args:
+             qubit: qubit/s to measure.
+             cbit: classical bit/s to place the measurement in.
+
+         Returns:
+             qiskit.circuit.InstructionSet: handle to the added instructions.
+
+         Raises:
+             CircuitError: if arguments have bad format.
         """
         return self.append(Measure(), [qubit], [cbit])