extend the documentation for qiskit.circuit.QuantumCircuit.measure

qiskit/circuit/quantumcircuit.py

@@ -2265,17 +2265,98 @@ 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).
+
+        When a qubit is measured, its state collapses to a classical bit and copied to a
+        classical wire.
 
         Args:
-            qubit: qubit to measure.
-            cbit: classical bit to place the measurement in.
+            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.
+
+        Examples:
+            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):
+
+            .. 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
+
         """
         return self.append(Measure(), [qubit], [cbit])