From 845746daff2b9bc8c7e66b9ca205b888d5224d92 Mon Sep 17 00:00:00 2001
From: Jake Lishman <jake.lishman@ibm.com>
Date: Mon, 24 Jul 2023 20:25:13 +0100
Subject: [PATCH] Fix documentation of `SwitchCaseOp` (#10484)

The class page for the `SwitchCaseOp` had some broken hyperlinks, and
the documentation of the switch `CASE_DEFAULT` object was broken.  This
fixes both, and adds some more explicit examples of usage of the
`CASE_DEFAULT` object, with some overlap of what was already in
`QuantumCircuit.switch`.
---
 qiskit/circuit/__init__.py                | 38 +++++++++++++++++++++--
 qiskit/circuit/controlflow/switch_case.py |  7 ++---
 2 files changed, 38 insertions(+), 7 deletions(-)

diff --git a/qiskit/circuit/__init__.py b/qiskit/circuit/__init__.py
index d319cabc418c..7c0548db797a 100644
--- a/qiskit/circuit/__init__.py
+++ b/qiskit/circuit/__init__.py
@@ -296,9 +296,41 @@
 
 The :class:`.SwitchCaseOp` also understands a special value:
 
-.. py:data: CASE_DEFAULT
-    Used as a possible "label" in a :class:`.SwitchCaseOp` to represent the default case.  This will
-    always match, if it is tried.
+.. py:data:: CASE_DEFAULT
+
+   A special object that represents the "default" case of a switch statement.  If you use this as a
+   case target, it must be the last case, and will match anything that wasn't already matched.  For
+   example::
+
+       from qiskit import QuantumCircuit, QuantumRegister, ClassicalRegister
+       from qiskit.circuit import SwitchCaseOp, CASE_DEFAULT
+
+       body0 = QuantumCircuit(2, 2)
+       body0.x(0)
+       body1 = QuantumCircuit(2, 2)
+       body1.z(0)
+       body2 = QuantumCircuit(2, 2)
+       body2.cx(0, 1)
+
+       qr, cr = QuantumRegister(2), ClassicalRegister(2)
+       qc = QuantumCircuit(qr, cr)
+       qc.switch(cr, [(0, body0), (1, body1), (CASE_DEFAULT, body2)], qr, cr)
+
+   When using the builder interface of :meth:`.QuantumCircuit.switch`, this can also be accessed as
+   the ``DEFAULT`` attribute of the bound case-builder object, such as::
+
+       from qiskit import QuantumCircuit, QuantumRegister, ClassicalRegister
+
+       qr, cr = QuantumRegister(2), ClassicalRegister(2)
+       qc = QuantumCircuit(qr, cr)
+       with qc.switch(cr) as case:
+           with case(0):
+               qc.x(0)
+           with case(1):
+               qc.z(0)
+           with case(case.DEFAULT):
+               qc.cx(0, 1)
+
 
 Parametric Quantum Circuits
 ---------------------------
diff --git a/qiskit/circuit/controlflow/switch_case.py b/qiskit/circuit/controlflow/switch_case.py
index 5fc4aac27bb9..0f215a9bcbb8 100644
--- a/qiskit/circuit/controlflow/switch_case.py
+++ b/qiskit/circuit/controlflow/switch_case.py
@@ -41,8 +41,7 @@ def __repr__(self):
 """A special object that represents the "default" case of a switch statement.  If you use this
 as a case target, it must be the last case, and will match anything that wasn't already matched.
 When using the builder interface of :meth:`.QuantumCircuit.switch`, this can also be accessed as the
-``DEFAULT`` attribute of the bound case-builder object.
-"""
+``DEFAULT`` attribute of the bound case-builder object."""
 
 
 class SwitchCaseOp(ControlFlowOp):
@@ -51,12 +50,12 @@ class SwitchCaseOp(ControlFlowOp):
     be used to represent a default condition.
 
     This is the low-level interface for creating a switch-case statement; in general, the circuit
-    method :meth:`.QuantumCircuit.switch_case` should be used as a context manager to access the
+    method :meth:`.QuantumCircuit.switch` should be used as a context manager to access the
     builder interface.  At the low level, you must ensure that all the circuit blocks contain equal
     numbers of qubits and clbits, and that the order the virtual bits of the containing circuit
     should be bound is the same for all blocks.  This will likely mean that each circuit block is
     wider than its natural width, as each block must span the union of all the spaces covered by
-    _any_ of the blocks.
+    *any* of the blocks.
 
     Args:
         target: the runtime value to switch on.