Minor documentation improvements and add a test with a register self-loop.

Author: fdxmw

pyrtl/gate_graph.py

@@ -119,7 +119,7 @@ class Gate:
        :attr:`~Gate.dest_bitwidth` will be ``None``. PyRTL does not have
        :attr:`ops<.LogicNet.op>` with multiple :attr:`~.LogicNet.dests`.
 
-    3. The :class:`Gate` has is a new :attr:`~Gate.dest_fanout` attribute, which has no
+    3. The :class:`Gate` has a new :attr:`~Gate.dest_fanout` attribute, which has no
        equivalent in the :class:`.LogicNet`/:class:`.WireVector` representation.
        :attr:`~Gate.dest_fanout` is a list of the :class:`Gates<Gate>` that use this
        :class:`Gate`'s output.
@@ -168,7 +168,7 @@ class Gate:
        track of the current object's type as we follow arrows in the graph, like we did
        with :class:`LogicNet` and :class:`WireVector`. Everything is a :class:`Gate`.
 
-    See the documentation for :class:`GateGraph` for examples.
+    For usage examples, see :class:`GateGraph` and :class:`Gate`'s documentation below.
     """
 
     op: str
@@ -233,7 +233,8 @@ class Gate:
 
     .. note::
 
-        The same ``Gate`` may appear multiple times in ``args``.
+        The same ``Gate`` may appear multiple times in ``args``. A :class:`.Register`
+        ``Gate`` may be its own ``arg``, creating a self-loop.
 
     .. doctest only::
 
@@ -312,9 +313,11 @@ class Gate:
     For each :class:`Gate` ``dest`` in ``self.dest_fanout``, ``self`` is in
     ``dest.args``.
 
-    ..note::
+    .. note::
 
-        The same :class:`Gate` may appear multiple times in ``dest_fanout``.
+        The same :class:`Gate` may appear multiple times in ``dest_fanout``. A
+        :class:`.Register` ``Gate`` may appear in its own ``dest_fanout``, creating a
+        self-loop.
 
     .. doctest only::
 
@@ -379,7 +382,7 @@ def __init__(
             :class:`.WireVector`. In this first phase, the register ``Gate``'s ``op`` is
             temporarily set to ``R``, which is the :class:`.Register`'s ``_code``. This
             placeholder is needed to resolve other ``Gate``'s references to the register
-            in the second phase. In the second phase, the register gate's remaining
+            in the second phase. In the second phase, the register ``Gate``'s remaining
             fields are populated from the register's :class:`.LogicNet`. In the second
             phase, the register ``Gate``'s ``op`` is changed to ``r``, which is the
             :class:`.LogicNet`'s :attr:`~.LogicNet.op`.
@@ -391,8 +394,8 @@ def __init__(
             :class:`.Register`.
 
         :param args: A :class:`list` of ``Gates`` that are inputs to this ``Gate``. This
-            corresponds to :attr:`.LogicNet.args`, except that each of these ``args`` is
-            a ``Gate``.
+            corresponds to :attr:`.LogicNet.args`, except that each of a ``Gate``'s
+            ``args`` is a ``Gate``.
         """
         self.op_param = None
         if args is None:
@@ -484,8 +487,9 @@ def __str__(self):
         - :attr:`~Gate.args` is ``[<Gate that produces tmp12>]``.
 
         - :attr:`~Gate.op_param` is ``(0, 1, 2, 3, 4, 5, 6, 7)``, written as ``sel``
-          because a ``slice``'s ``op_param`` determines the selected bits. This improves
-          readability.
+          because a ``slice``'s :attr:`~Gate.op_param` determines the selected bits.
+          This improves readability by indicating what the :attr:`~Gate.op_param` means
+          for the :attr:`~Gate.op`.
         """
         if self.dest_name is None:
             dest = ""
@@ -638,8 +642,9 @@ class GateGraph:
         defines the register's :attr:`~.Register.next` value (which is the register
         :class:`Gate`'s :attr:`~Gate.args`) can depend on the register's current value
         (which is the register :class:`Gate`'s ``dest``). Watch out for infinite loops
-        when traversing a :class:`GateGraph` with registers, if you keep following
-        :attr:`~Gate.dest_fanout` references you may end up back where you started.
+        when traversing a :class:`GateGraph` with registers. For example, if you keep
+        following :attr:`~Gate.dest_fanout` references, you may end up back where you
+        started.
     """
 
     gates: list[Gate]

tests/test_gate_graph.py

@@ -99,6 +99,7 @@ def test_gate_attrs(self):
 
         a_gate = gate_graph.get_gate("a")
         self.assertEqual(a_gate.op, "I")
+        self.assertEqual(a_gate.args, [])
 
         b_gate = gate_graph.get_gate("b")
         self.assertEqual(b_gate.op, "C")
@@ -199,6 +200,20 @@ def test_register_gate_backward(self):
 
         self.assertEqual(plus_gate.args[0], counter_gate)
 
+    def test_register_self_loop(self):
+        """Test a register that sets its next value directly from itself.
+
+        This is an unusual case that creates a self-loop in the ``GateGraph``.
+        """
+        r = pyrtl.Register(name="r", bitwidth=1)
+        r.next <<= r
+
+        gate_graph = pyrtl.GateGraph()
+        r_gate = gate_graph.get_gate("r")
+        self.assertEqual(r_gate.args[0], r_gate)
+        self.assertEqual(r_gate.dest_fanout[0], r_gate)
+        self.assertEqual(str(r_gate), "r/1 = reg(r/1) [reset_value=0]")
+
     def test_memblock(self):
         mem = pyrtl.MemBlock(name="mem", bitwidth=8, addrwidth=2)