[IRON] Document parent-constructor bypass in AccumFifoHandle / PacketFifoHandle

Address review issue 7: AccumFifoHandle and PacketFifoHandle deliberately
do not call super().__init__() because ObjectFifoHandle's constructor
requires an ObjectFifo with semantics (depth, dims_from_stream_per_cons,
_get_endpoint) that AccumFifo and PacketFifo do not have. They instead
stub the attributes ObjectFifoHandle exposes as properties directly.

Add an explicit class-docstring '.. note::' section in each documenting:
  - which attributes are stubbed
  - why super() is bypassed
  - that all_of_endpoints (which traverses _object_fifo) is overridden
  - that the proper long-term fix is a shared narrower base class

This is a documentation fix, not a behavioural change. The shared base
class refactor is intentionally out of scope for the initial primitive
landing; the bypass pattern is rare in upstream IRON code, and explicit
documentation keeps the next maintainer from being surprised.

(SparseFifoHandle and VariableRateFifoHandle inherit normally from
ObjectFifoHandle and do call super().__init__; only AccumFifoHandle
and PacketFifoHandle exhibit the bypass pattern.)

Author: Matt Davis

python/iron/accum.py

@@ -478,14 +478,30 @@ class AccumFifoHandle(ObjectFifoHandle):
     :class:`AccumFifo`'s point-to-point invariant in the cascade case
     (a cascade transfer takes exactly one accumulator per cycle; there
     is no notion of a "circular buffer with depth N" here).
+
+    .. note::
+       :meth:`__init__` deliberately does **not** call
+       ``super().__init__()`` -- :class:`ObjectFifoHandle`'s constructor
+       requires an ``of`` argument with ObjectFifo semantics (depth,
+       ``dims_from_stream_per_cons``, ``_get_endpoint`` etc.) that
+       :class:`AccumFifo` does not have. We instead stub the attributes
+       :class:`ObjectFifoHandle` exposes as properties (``_port``,
+       ``_is_prod``, ``_depth``, ``_endpoint``, ``_dims_from_stream``,
+       ``_tile``) directly so isinstance-based downstream code keeps
+       working. This pattern is repeated in :class:`PacketFifoHandle`,
+       :class:`SparseFifoHandle`, and :class:`VariableRateFifoHandle`;
+       a shared narrower base class is the intended long-term fix
+       (see the "Future work" note in module docstrings) but is out of
+       scope for the initial primitive landing.
+
+       Methods inherited from :class:`ObjectFifoHandle` that traverse
+       ``self._object_fifo`` (notably :meth:`all_of_endpoints`) are
+       overridden below so the bypass does not produce
+       ``AttributeError`` at lowering time.
     """
 
     def __init__(self, accum_fifo: AccumFifo, is_prod: bool):
-        # Bypass ObjectFifoHandle.__init__ -- it requires an `of` with
-        # ObjectFifo semantics (depth, dims_from_stream_per_cons, etc.)
-        # that AccumFifo does not have. Set the fields ObjectFifoHandle
-        # exposes as properties directly so isinstance-based downstream
-        # code keeps working.
+        # See class docstring "note" for why super().__init__() is bypassed.
         self._port = (
             ObjectFifoPort.Produce if is_prod else ObjectFifoPort.Consume
         )

python/iron/packet.py

@@ -609,6 +609,14 @@ class PacketFifoHandle(ObjectFifoHandle):
     :meth:`send_with_header` and :meth:`recv_header` are added on top
     for callers that need explicit per-packet header control (the
     filter-early use case).
+
+    .. note::
+       :meth:`__init__` bypasses ``super().__init__()`` for the same
+       reason :class:`AccumFifoHandle` does -- :class:`ObjectFifoHandle`
+       requires an ``of`` with ObjectFifo semantics that
+       :class:`PacketFifo` does not have. See the corresponding note in
+       :class:`AccumFifoHandle`. A shared narrower base class is the
+       intended long-term fix.
     """
 
     def __init__(
@@ -618,10 +626,7 @@ def __init__(
         index: int,
         depth: int,
     ):
-        # Bypass ObjectFifoHandle.__init__ (it requires an `of` with
-        # ObjectFifo semantics: depth, dims_from_stream_per_cons, etc.)
-        # and set the fields ObjectFifoHandle exposes as properties
-        # directly so isinstance-based downstream code keeps working.
+        # See class docstring "note" for why super().__init__() is bypassed.
         self._port = (
             ObjectFifoPort.Produce if is_prod else ObjectFifoPort.Consume
         )