docs/{guide,reference}: clarify semantics of a.any() vs a.bool().

Author: whitequark

amaranth/hdl/_ast.py

@@ -622,7 +622,8 @@ def __bool__(self):
     def bool(self):
         """Conversion to boolean.
 
-        Performs the same operation as :meth:`any`.
+        Returns the same value as :meth:`any`, but should be used where :py:`self` is semantically
+        a number.
 
         Returns
         -------
@@ -934,6 +935,9 @@ def __ror__(self, other):
     def any(self):
         """Reduction OR; is any bit :py:`1`?
 
+        Performs the same operation as :meth:`bool`, but should be used where :py:`self` is
+        semantically a bit sequence.
+
         Returns
         -------
         :class:`Value`, :py:`unsigned(1)`
@@ -2072,7 +2076,7 @@ def __init__(self, shape=None, *, name=None, init=None, reset=None, reset_less=F
 
         if decoder is not None:
             # The value representation is specified explicitly. Since we do not expose `hdl._repr`,
-            # this is the only way to add a custom filter to the signal right now. 
+            # this is the only way to add a custom filter to the signal right now.
             if isinstance(decoder, type) and issubclass(decoder, Enum):
                 self._value_repr = (_repr.Repr(_repr.FormatEnum(decoder), self),)
             else:

docs/guide.rst

@@ -610,13 +610,14 @@ The following table lists the reduction operations provided by Amaranth:
 Operation    Description                                   Notes
 ============ ============================================= ======
 ``a.all()``  reduction AND; are all bits set?              [#opR1]_
-``a.any()``  reduction OR; is any bit set?                 [#opR1]_
+``a.any()``  reduction OR; is any bit set?                 [#opR1]_ [#opR3]_
 ``a.xor()``  reduction XOR; is an odd number of bits set?
-``a.bool()`` conversion to boolean; is non-zero?           [#opR2]_
+``a.bool()`` conversion to boolean; is non-zero?           [#opR2]_ [#opR3]_
 ============ ============================================= ======
 
 .. [#opR1] Conceptually the same as applying the Python :func:`all` or :func:`any` function to the value viewed as a collection of bits.
-.. [#opR2] Conceptually the same as applying the Python :func:`bool` function to the value viewed as an integer.
+.. [#opR2] Conceptually the same as applying the Python :class:`bool` function to the value viewed as an integer.
+.. [#opR3] While the :meth:`Value.any()` and :meth:`Value.bool`  operators return the same value, the use of ``a.any()`` implies that ``a`` is semantically a bit sequence, and the use of ``a.bool()`` implies that ``a`` is semantically a number.
 
 
 .. _lang-logicops: