From b5428812a13bb8458f9a14c699184be76129e8b0 Mon Sep 17 00:00:00 2001
From: Jeremy Lau <30300826+fdxmw@users.noreply.github.com>
Date: Fri, 17 May 2024 17:13:51 -0700
Subject: [PATCH] Documentation improvement: Add links to signed operations
 (`signed_*` functions) from the corresponding unsigned WireVector operations.

Also some minor rewording in example1.1.
---
 examples/example1.1-signed-numbers.py | 12 ++++++------
 examples/example2-counter.py          |  4 ----
 pyrtl/wire.py                         | 20 +++++++++++++-------
 3 files changed, 19 insertions(+), 17 deletions(-)

diff --git a/examples/example1.1-signed-numbers.py b/examples/example1.1-signed-numbers.py
index 572c5a91..d4b45e9c 100644
--- a/examples/example1.1-signed-numbers.py
+++ b/examples/example1.1-signed-numbers.py
@@ -89,9 +89,8 @@
 # Manually sign-extend inputs to correctly add signed integers with `+`.
 # ▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
 # Instead of using `signed_add`, we can manually sign-extend the inputs and
-# truncate the output to correctly add signed integers with `+`.
-#
-# Use this trick to implement other signed arithmetic operations.
+# truncate the output to correctly add signed integers with `+`. Use this trick
+# to implement other signed arithmetic operations.
 pyrtl.reset_working_block()
 
 a = pyrtl.Input(bitwidth=2, name='a')
@@ -100,8 +99,8 @@
 # Using `+` produces the correct result for signed addition here because we
 # manually extend `a` and `b` to 3 bits. The result of `a.sign_extended(3) +
 # b.sign_extended(3)` is now 4 bits, but we truncate it to 3 bits. This
-# truncation is important! The addition's full 4 bit result would not be
-# correct.
+# truncation is subtle, but important! The addition's full 4 bit result would
+# not be correct.
 sign_extended_sum = pyrtl.Output(bitwidth=3, name='sign_extended_sum')
 extended_a = a.sign_extended(bitwidth=3)
 extended_b = b.sign_extended(bitwidth=3)
@@ -117,5 +116,6 @@
 
 print('\nInstead of using `signed_add`, we can also manually sign extend the '
       'inputs to\ncorrectly add signed integers with `+`.\n'
-      'sign_extended_sum == a.sign_extended(3) + b.sign_extended(3)')
+      'sign_extended_sum == (a.sign_extended(3) + b.sign_extended(3))'
+      '.truncate(3)')
 sim.tracer.render_trace(repr_func=pyrtl.val_to_signed_integer)
diff --git a/examples/example2-counter.py b/examples/example2-counter.py
index 94464c92..eb92c811 100644
--- a/examples/example2-counter.py
+++ b/examples/example2-counter.py
@@ -80,7 +80,3 @@ def ripple_add(a, b, carry_in=0):
     sim.step({})
     assert sim.value[counter] == cycle % 8
 sim_trace.render_trace()
-
-# All done.
-
-exit(0)
diff --git a/pyrtl/wire.py b/pyrtl/wire.py
index 1ac526a1..89783599 100644
--- a/pyrtl/wire.py
+++ b/pyrtl/wire.py
@@ -305,7 +305,7 @@ def __ixor__(self, other):
     def __add__(self, other):
         """Adds two wires together into a single WireVector.
 
-        Addition is *unsigned*.
+        Addition is *unsigned*. Use :func:`.signed_add` for signed addition.
 
         :rtype: WireVector
         :return: Returns the result wire of the operation. The resulting wire
@@ -330,7 +330,8 @@ def __iadd__(self, other):
     def __sub__(self, other):
         """Subtracts the right wire from the left one.
 
-        Subtraction is *unsigned*.
+        Subtraction is *unsigned*. Use :func:`.signed_sub` for signed
+        subtraction.
 
         :rtype: WireVector
         :return: Returns the result wire of the operation. The resulting wire
@@ -350,7 +351,8 @@ def __isub__(self, other):
     def __mul__(self, other):
         """Multiplies two WireVectors.
 
-        Multiplication is *unsigned*.
+        Multiplication is *unsigned*. Use :func:`.signed_mult` for signed
+        multiplication.
 
         :rtype: WireVector
         :return: Returns the result wire of the operation. The resulting wire's
@@ -368,7 +370,8 @@ def __imul__(self, other):
     def __lt__(self, other):
         """Calculates whether a wire is less than another.
 
-        The comparison is *unsigned*.
+        The comparison is *unsigned*. Use :func:`.signed_lt` for a signed
+        comparison.
 
         :rtype: WireVector
         :return: a one bit result wire of the operation
@@ -379,7 +382,8 @@ def __lt__(self, other):
     def __le__(self, other):
         """Calculates whether a wire is less than or equal to another.
 
-        The comparison is *unsigned*.
+        The comparison is *unsigned*. Use :func:`.signed_le` for a signed
+        comparison.
 
         :rtype: WireVector
         :return: a one bit result wire of the operation
@@ -408,7 +412,8 @@ def __ne__(self, other):
     def __gt__(self, other):
         """Calculates whether a wire is greater than another.
 
-        The comparison is *unsigned*.
+        The comparison is *unsigned*. Use :func:`.signed_gt` for a signed
+        comparison.
 
         :rtype: WireVector
         :return: a one bit result wire of the operation
@@ -419,7 +424,8 @@ def __gt__(self, other):
     def __ge__(self, other):
         """Calculates whether a wire is greater than or equal to another.
 
-        The comparison is *unsigned*.
+        The comparison is *unsigned*. Use :func:`.signed_ge` for a signed
+        comparison.
 
         :rtype: WireVector
         :return: a one bit result wire of the operation