Repository: Qiskit/qiskit

Issue:
Documentation: Impove CASE_DEFAULT documentation
### What should we add?

From https://qiskit.org/documentation/stubs/qiskit.circuit.SwitchCaseOp.html:
> The special value CASE_DEFAULT can be used to represent a default condition.

But it doesn't explain how to import `CASE_DEFAULT` and there is no hyperlink.


Discussion:
Yeah, it's meant to hyperlink to an entry right underneath [this table of the control-flow ops](https://qiskit.org/documentation/apidoc/circuit.html#control-flow-operations), but I must have screwed up the Sphinx syntax, because that entry hasn't actually been build, so there's nothing to link to.

I'll fix it tomorrow, because I don't want to put up a new PR right now while we're in a CI concurrency crunch for the 0.25.0rc1 release today (or early tomorrow if we can't get through CI).

Resolving patch:
diff --git a/qiskit/circuit/__init__.py b/qiskit/circuit/__init__.py
--- 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
--- 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.


Test patch: