extend the documentation for qiskit.circuit.QuantumCircuit.measure (#…

…9698)

* extend the documentation for qiskit.circuit.QuantumCircuit.measure

* spelling

* H

* qregs and cregs

* spelling

* Update qiskit/circuit/quantumcircuit.py

* Update qiskit/circuit/quantumcircuit.py

* Update qiskit/circuit/quantumcircuit.py

* Update qiskit/circuit/quantumcircuit.py

* examples after Args/Return/Raises

* Update qiskit/circuit/quantumcircuit.py

Co-authored-by: Jake Lishman <jake@binhbar.com>

* short description

* better description

* as equivalence

* shorten it a bit

* ::

* raw string

* lvert

* Tweak grammar

---------

Co-authored-by: Junye Huang <h.jun.ye@gmail.com>
Co-authored-by: Jake Lishman <jake@binhbar.com>
(cherry picked from commit 6bb4957)

qiskit/circuit/quantumcircuit.py

@@ -2262,17 +2262,77 @@ 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).
+        r"""Measure a quantum bit (``qubit``) in the Z basis into a classical bit (``cbit``).
+
+        When a quantum state is measured, a qubit is projected in the computational (Pauli Z) basis
+        to either :math:`\lvert 0 \rangle` or :math:`\lvert 1 \rangle`. The classical bit ``cbit``
+        indicates the result
+        of that projection as a ``0`` or a ``1`` respectively. This operation is non-reversible.
 
         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 result(s) 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`` as a shortcut
+            for one-to-one measurement. These two forms produce identical results:
+
+            .. code-block::
+
+               circuit = QuantumCircuit(2, 2)
+               circuit.measure([0,1], [0,1])
+
+            .. code-block::
+
+               circuit = QuantumCircuit(2, 2)
+               circuit.measure(0, 0)
+               circuit.measure(1, 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(2, "qreg")
+                creg = ClassicalRegister(2, "creg")
+                circuit = QuantumCircuit(qreg, creg)
+                circuit.measure(qreg, creg)
+
+            This is equivalent to:
+
+            .. code-block::
+
+                circuit = QuantumCircuit(qreg, creg)
+                circuit.measure(qreg[0], creg[0])
+                circuit.measure(qreg[1], creg[1])
+
         """
         return self.append(Measure(), [qubit], [cbit])