Improve documentation for wire_struct's _value constructor argument.

Author: fdxmw

pyrtl/helperfuncs.py

@@ -1470,22 +1470,17 @@ def wire_struct(wire_struct_spec):
 
     1. Provide a driver for *each* component wire, for example::
 
-            >>> byte = Byte(high=0xA, low=0xB)
+           >>> byte = Byte(high=0xA, low=0xB)
 
        Note how the component names (``high``, ``low``) are used as keyword args for the
        constructor. Drivers must be provided for *all* components.
 
     2. Provide a driver for the entire ``@wire_struct``, for example::
 
-            >>> byte = Byte(Byte=0xAB)
+           >>> byte = Byte(Byte=0xAB)
 
        Note how the class name (``Byte``) is used as a keyword arg for the constructor.
 
-       If the class name is not known, the special name ``_value`` can be used instead::
-
-            >>> UnknownDynamicType = Byte
-            >>> unknown_dynamic_type = UnknownDynamicType(_value=0xAB)
-
     Accessing Slices
     ----------------
 
@@ -1620,6 +1615,41 @@ class CacheLine:
 
         No values are specified for ``input_byte`` because its value is not known until
         simulation time.
+
+    Generic Usage
+    -------------
+
+    .. doctest only::
+
+        >>> import pyrtl
+        >>> pyrtl.reset_working_block()
+
+    Functions can work with ``@wire_struct`` instances generically. For example, we can
+    define a function that accepts any ``@wire_struct`` and returns the same type of
+    ``@wire_struct``, with all of the argument's fields bitwise-inverted::
+
+        >>> def invert_all_fields(output_name, any_wire_struct):
+        ...     # Retrieve the argument wire_struct's class.
+        ...     OutputClass = type(any_wire_struct)
+        ...     # Instantiate that class, specifying its full value.
+        ...     return OutputClass(name=output_name, _value=~any_wire_struct)
+
+        >>> input_byte = Byte(name="input_byte", concatenated_type=pyrtl.Input)
+        >>> output_byte = invert_all_fields("output_byte", input_byte)
+
+        >>> sim = pyrtl.Simulation()
+        >>> sim.step({"input_byte": 0})
+        >>> hex(sim.inspect("output_byte"))
+        '0xff'
+
+    ``invert_all_fields`` uses ``type(any_wire_struct)`` to retrieve the argument
+    ``@wire_struct``'s class, and instantiates that class for the function's return
+    value.
+
+    This uses the special constructor ``kwarg`` ``_value``, rather than the name of the
+    class, to specify the full value for the returned ``@wire_struct`` object. In this
+    example, we must use ``_value`` instead of the name of the class (``Byte``) because
+    ``any_wire_struct`` might not be a ``Byte``.
     """
     # Convert the decorated class' annotations (dict of attr_name: attr_value)
     # to a list of _ComponentMetas.