add some documentation to the spec modules

diff --git a/src/spec/interfaces.py b/src/spec/interfaces.py
index 51d14b164b56006e1f8e99d980e67de83078fb3c..27b008fe33696a76f72a19af912cde9ab0dfa8eb 100644 (file)
--- a/src/spec/interfaces.py
+++ b/src/spec/interfaces.py
@@ -14,6 +14,13 @@ def namesuffix(name, suffix, namelist):
 
 
 class PinGen(object):
+    """ a meta-helper which creates pins from the pinspec
+        and adds them to the pinouts.
+
+        __call__ is used to effectively create a lambda function, which
+        in combination with setattr (below) gives the function a name
+        in the Pinouts class, according to the pinspec.
+    """
     def __init__(self, pinouts, fname, pinfn, bankspec):
         self.pinouts = pinouts
         self.bankspec = bankspec
@@ -27,9 +34,9 @@ class PinGen(object):
             prefix, pingroup = pingroup
         else:
             prefix = self.fname
-        if start and limit:
+        if start and limit: # limit turns into an offset from start
             limit = start + limit
-        pingroup = pingroup[start:limit]
+        pingroup = pingroup[start:limit] # see comment in spec.pinfunctions
         pins = Pins(prefix, pingroup, self.bankspec,
                     suffix, offs, bank, mux,
                     spec, origsuffix=suffix)

diff --git a/src/spec/pinfunctions.py b/src/spec/pinfunctions.py
index d41a3544552cf82e79d13d037202154d13581a59..9705e8c5d32c93e36fd426717d89280d5a2f646c 100644 (file)
--- a/src/spec/pinfunctions.py
+++ b/src/spec/pinfunctions.py
@@ -1,5 +1,32 @@
 #!/usr/bin/env python
 
+""" define functions here, with their pin names and the pin type.
+
+    each function returns a list (or an object with a __getitem__ function)
+    containing pin name plus type specifications.
+
+    the type is:
+
+    * "-" for an input pin,
+    * "+" for an output pin,
+    * "*" for an in/out pin
+
+    each function is then added to the pinspec tuple, below, as a ("NAME",
+    function) entry.
+
+    different functions may be added multiple times under the same NAME,
+    so that complex (or large) functions can be split into one or more
+    groups (and placed on different pinbanks).
+
+    eint, pwm and gpio are slightly odd in that instead of a fixed list
+    an object is returned with a __getitem__ function that accepts a
+    slice object.  in this way the actual generation of the pin name
+    is delayed until it is known precisely how many pins are to be
+    generated, and that's not known immediately (or it would be if
+    every single one of the functions below had a start and end parameter
+    added).  see spec.interfaces.PinGen class slice on pingroup
+"""
+
 def i2s(suffix, bank):
     return ['MCK+', 'BCK+', 'LRCK+', 'DI-', 'DO+']