Add doctest examples for rtllib/adders.py.

Author: fdxmw

pyrtl/rtllib/adders.py

@@ -24,6 +24,24 @@ def kogge_stone(
     useful for performance critical designs. However, it has `O(n log(n))` area usage,
     and large fan out.
 
+    .. doctest only::
+
+        >>> import pyrtl
+        >>> pyrtl.reset_working_block()
+
+    Example::
+
+        >>> a = pyrtl.Input(name="a", bitwidth=4)
+        >>> b = pyrtl.Input(name="b", bitwidth=4)
+        >>> output = pyrtl.Output(name="output")
+
+        >>> output <<= pyrtl.rtllib.adders.kogge_stone(a, b)
+
+        >>> sim = pyrtl.Simulation()
+        >>> sim.step(provided_inputs={"a": 2, "b": 3})
+        >>> sim.inspect("output")
+        5
+
     :param a: A :class:`.WireVector` to add up. Bitwidths don't need to match.
     :param b: A :class:`.WireVector` to add up. Bitwidths don't need to match.
     :param cin: An optional 1-bit carry-in :class:`.WireVector`. Can be any type that
@@ -103,6 +121,25 @@ def carrysave_adder(
 ) -> pyrtl.WireVector:
     """Adds three :class:`WireVectors<.WireVector>` up in an efficient manner.
 
+    .. doctest only::
+
+        >>> import pyrtl
+        >>> pyrtl.reset_working_block()
+
+    Example::
+
+        >>> a = pyrtl.Input(name="a", bitwidth=4)
+        >>> b = pyrtl.Input(name="b", bitwidth=4)
+        >>> c = pyrtl.Input(name="c", bitwidth=4)
+        >>> output = pyrtl.Output(name="output")
+
+        >>> output <<= pyrtl.rtllib.adders.carrysave_adder(a, b, c)
+
+        >>> sim = pyrtl.Simulation()
+        >>> sim.step(provided_inputs={"a": 2, "b": 3, "c": 4})
+        >>> sim.inspect("output")
+        9
+
     :param a: A :class:`.WireVector` to add up. Bitwidths don't need to match.
     :param b: A :class:`.WireVector` to add up. Bitwidths don't need to match.
     :param c: A :class:`.WireVector` to add up. Bitwidths don't need to match.
@@ -128,6 +165,24 @@ def cla_adder(
     calculates the carry bits faster. It is not as fast as :func:`kogge_stone`, but uses
     less area.
 
+    .. doctest only::
+
+        >>> import pyrtl
+        >>> pyrtl.reset_working_block()
+
+    Example::
+
+        >>> a = pyrtl.Input(name="a", bitwidth=4)
+        >>> b = pyrtl.Input(name="b", bitwidth=4)
+        >>> output = pyrtl.Output(name="output")
+
+        >>> output <<= pyrtl.rtllib.adders.cla_adder(a, b)
+
+        >>> sim = pyrtl.Simulation()
+        >>> sim.step(provided_inputs={"a": 2, "b": 3})
+        >>> sim.inspect("output")
+        5
+
     :param a: A :class:`.WireVector` to add up. Bitwidths don't need to match.
     :param b: A :class:`.WireVector` to add up. Bitwidths don't need to match.
     :param cin: A 1-bit carry-in :class:`.WireVector`.
@@ -322,6 +377,26 @@ def fast_group_adder(
 
         max(len(w) for w in wires_to_add) + ceil(len(wires_to_add))
 
+    .. doctest only::
+
+        >>> import pyrtl
+        >>> pyrtl.reset_working_block()
+
+    Example::
+
+        >>> wires_to_add = [pyrtl.Const(n) for n in range(10)]
+        >>> output = pyrtl.Output(name="output")
+
+        >>> output <<= pyrtl.rtllib.adders.fast_group_adder(wires_to_add)
+
+        >>> sim = pyrtl.Simulation()
+        >>> sim.step()
+        >>> sim.inspect("output")
+        45
+        >>> sum(range(10))
+        45
+
+
     :param wires_to_add: A :class:`list` of :class:`WireVectors<.WireVector>` to add.
     :param reducer: The tree reducer to use. See :func:`wallace_reducer` and
         :func:`dada_reducer`.

tests/rtllib/test_adders.py

@@ -1,3 +1,4 @@
+import doctest
 import random
 import unittest
 
@@ -6,6 +7,15 @@
 from pyrtl.rtllib import adders
 
 
+class TestDocTests(unittest.TestCase):
+    """Test documentation examples."""
+
+    def test_doctests(self):
+        failures, tests = doctest.testmod(m=pyrtl.rtllib.adders)
+        self.assertGreater(tests, 0)
+        self.assertEqual(failures, 0)
+
+
 class TestAdders(unittest.TestCase):
     @classmethod
     def setUpClass(cls):