From 99c151ff94be11a60ee0c8f02be3be131756be40 Mon Sep 17 00:00:00 2001
From: Luke Kenneth Casson Leighton <lkcl@lkcl.net>
Date: Sun, 28 Apr 2019 00:05:48 +0100
Subject: [PATCH] add docstrings

---
 src/add/iocontrol.py     | 32 +++++++++++++++++++++-----------
 src/add/test_buf_pipe.py |  3 ++-
 2 files changed, 23 insertions(+), 12 deletions(-)

diff --git a/src/add/iocontrol.py b/src/add/iocontrol.py
index c3da0463..2e18312a 100644
--- a/src/add/iocontrol.py
+++ b/src/add/iocontrol.py
@@ -19,17 +19,26 @@
 
     the methods of a stage instance must be as follows:
 
-    * ispec() - Input data format specification
-                returns an object or a list or tuple of objects, or
-                a Record, each object having an "eq" function which
-                takes responsibility for copying by assignment all
-                sub-objects
-    * ospec() - Output data format specification
-                requirements as for ospec
-    * process(m, i) - Processes an ispec-formatted object
+    * ispec() - Input data format specification.  Takes a bit of explaining.
+                The requirements are: something that eventually derives from
+                nmigen Value must be returned *OR* an iterator or iterable
+                or sequence (list, tuple etc.) or generator must *yield*
+                thing(s) that (eventually) derive from the nmigen Value
+                class.  Complex to state, very simple in practice:
+                see test_buf_pipe.py for over 25 working examples.
+
+    * ospec() - Output data format specification.
+                requirements identical to ispec
+
+    * process(m, i) - Processes an ispec-formatted object/sequence
                 returns a combinatorial block of a result that
-                may be assigned to the output, by way of the "eq"
-                function
+                may be assigned to the output, by way of the "nmoperator.eq"
+                function.  Note that what is returned here can be
+                extremely flexible.  Even a dictionary can be returned
+                as long as it has fields that match precisely with the
+                Record into which its values is intended to be assigned.
+                Again: see example unit tests for details.
+
     * setup(m, i) - Optional function for setting up submodules
                 may be used for more complex stages, to link
                 the input (i) to submodules.  must take responsibility
@@ -40,7 +49,8 @@
     Both StageCls (for use with non-static classes) and Stage (for use
     by static classes) are abstract classes from which, for convenience
     and as a courtesy to other developers, anything conforming to the
-    Stage API may *choose* to derive.
+    Stage API may *choose* to derive.  See Liskov Substitution Principle:
+    https://en.wikipedia.org/wiki/Liskov_substitution_principle
 
     StageChain:
     ----------
diff --git a/src/add/test_buf_pipe.py b/src/add/test_buf_pipe.py
index 892e3ace..7155c908 100644
--- a/src/add/test_buf_pipe.py
+++ b/src/add/test_buf_pipe.py
@@ -480,6 +480,7 @@ class ExampleAddRecordPlaceHolderStage(StageCls):
         return o
 
 
+# a dummy class that may have stuff assigned to instances once created
 class PlaceHolder: pass
 
 
@@ -547,7 +548,7 @@ class ExampleAddClassStage(StageCls):
         """ returns an output signal which will happen to contain the sum
             of the two inputs
         """
-        return Signal(16)
+        return Signal(16, name="add2_out")
 
     def process(self, i):
         """ process the input data (sums the values in the tuple) and returns it
-- 
2.30.2