update ControlBase docstrings, throw assert if pipechain is zero length

diff --git a/src/add/iocontrol.py b/src/add/iocontrol.py
index e0a6e0cbf9d0ae55bb61d4371d133ccbe9ae33c5..66c67c94e8f1f846f69dbe7940ec54cfbc761734 100644 (file)
--- a/src/add/iocontrol.py
+++ b/src/add/iocontrol.py
@@ -397,7 +397,9 @@ class StageChain(StageCls):
 
 
 class ControlBase(Elaboratable):
-    """ Common functions for Pipeline API
+    """ Common functions for Pipeline API.  Note: a "pipeline stage" only
+        exists (conceptually) when a ControlBase derivative is handed
+        a Stage (combinatorial block)
     """
     def __init__(self, stage=None, in_multi=None, stage_ctl=False):
         """ Base class containing ready/valid/data to previous and next stages
@@ -466,7 +468,18 @@ class ControlBase(Elaboratable):
             Thus it becomes possible to build up larger chains recursively.
             More complex chains (multi-input, multi-output) will have to be
             done manually.
+
+            Argument:
+
+            * :pipechain: - a sequence of ControlBase-derived classes
+                            (must be one or more in length)
+
+            Returns:
+
+            * a list of eq assignments that will need to be added in
+              an elaborate() to m.d.comb
         """
+        assert len(pipechain > 0), "pipechain must be non-zero length"
         eqs = [] # collated list of assignment statements
 
         # connect inter-chain
@@ -527,4 +540,3 @@ class ControlBase(Elaboratable):
 
         return m
 
-