1 files changed, 34 insertions, 1 deletions
diff --git a/rfc1982_serial_number.py b/rfc1982_serial_number.py
index e46974a..bb9988c 100755
--- a/rfc1982_serial_number.py
+++ b/rfc1982_serial_number.py
@@ -1,6 +1,34 @@
 #!/usr/bin/env python3
 
+"""Implementation of RFC 1982 Serial Number Arithmetic.
+
+Run as a program, this takes start and finish serial values and tells
+you what intermediate steps (if any) are needed to make the specified
+change.
+
+Used as a module, this implements the Serial class and an iterator
+which returns the intermediate steps (if any) needed between two
+Serial values.
+"""
+
 class Serial:
+    """Implementation of RFC 1982 Serial Number Arithmetic.
+
+    Per the RFC, only two operations are defined on Serial objects:
+    addition and comparision, both within a restricted range specified
+    by the RFC.
+
+    The default modulus is 2**32, you can change this by subclassing
+    the Serial class and overriding the class's modulus variable.  The
+    modulus must be a power of two.
+
+    See RFC 1982 for discussion of the ways in which Serial numbers do
+    not work like normal integers.  In particular, note that there's a
+    corner case in which one can have a pair of Serial numbers I1 and
+    I2 where I1 is neither equal to, less than, nor greater than I2.
+    This is deliberate and is not a bug in the code.  See the RFC.
+
+    """
 
     modulus = 2 ** 32
 
@@ -40,6 +68,11 @@ class Serial:
         return f"{int(self):{len(str(self.modulus))}d}"
 
 def find_intermediate(start, finish):
+    """
+    Find the sequence of intermediate values (if any) needed to step
+    from start to finish
+    """
+
     while not (start < finish): # sic: serial numbers are not (quite) integers
         start += ((Serial.modulus >> 1) - 1)
         yield start
@@ -47,7 +80,7 @@ def find_intermediate(start, finish):
 def main():
     from argparse import ArgumentParser
 
-    ap = ArgumentParser()
+    ap = ArgumentParser(description = __doc__)
     ap.add_argument("start", type = Serial)
     ap.add_argument("finish", type = Serial)
     args = ap.parse_args()