Restore documentation for enum_mux and add a doctest example.

Author: fdxmw

docs/helpers.rst

@@ -38,6 +38,7 @@ Control Flow Hardware
 
 .. autofunction:: pyrtl.mux
 .. autofunction:: pyrtl.select
+.. autofunction:: pyrtl.enum_mux
 .. autoclass:: pyrtl.helperfuncs.MatchedFields
     :members:
     :undoc-members:

pyrtl/corecircuits.py

@@ -987,21 +987,40 @@ def enum_mux(
 ) -> WireVector:
     """Build a mux for the control signals specified by an :class:`enum.IntEnum`.
 
-    .. WARNING::
+    .. note::
+
+        Consider using :ref:`conditional_assignment` instead.
+
+    .. doctest only::
+
+        >>> import pyrtl
+        >>> pyrtl.reset_working_block()
+
+    Example::
+
+        >>> from enum import IntEnum
+        >>> class Command(IntEnum):
+        ...     ADD = 0
+        ...     SUB = 1
 
-        Use :ref:`conditional_assignment` instead.
+        >>> command = pyrtl.Input(name="command", bitwidth=1)
+        >>> a = pyrtl.Input(name="a", bitwidth=4)
+        >>> b = pyrtl.Input(name="b", bitwidth=4)
+        >>> output = pyrtl.Output(name="output")
 
-    Examples::
+        >>> output <<= pyrtl.enum_mux(cntrl=command, table={
+        ...     Command.ADD: a + b,
+        ...     Command.SUB: a - b,
+        ... })
 
-        from enum import IntEnum
+        >>> sim = pyrtl.Simulation()
+        >>> sim.step(provided_inputs={"command": Command.ADD, "a": 1, "b": 2})
+        >>> sim.inspect("output")
+        3
 
-        class Command(IntEnum):
-            ADD = 1
-            SUB = 2
-        enum_mux(cntrl, {Command.ADD: a + b, Command.SUB: a - b})
-        enum_mux(cntrl, {Command.ADD: a + b}, strict=False)  # SUB case undefined
-        enum_mux(cntrl, {Command.ADD: a + b, otherwise: a - b})
-        enum_mux(cntrl, {Command.ADD: a + b}, default=a - b)
+        >>> sim.step(provided_inputs={"command": Command.SUB, "a": 5, "b": 3})
+        >>> sim.inspect("output")
+        2
 
     :param cntrl: Control for the mux.
     :param table: Maps :class:`enum.IntEnum` values to :class:`WireVector`.