secret-sharing: improve docs for singleTerm

secret-sharing/interpolate.py

@@ -5,9 +5,20 @@
 def single_term(points, i):
     """Return one term of an interpolated polynomial.
 
+    This method computes one term of the sum from the proof of Theorem 2.2.
+    In particular, it computes:
+
+      y_i \product_{j=0}^n (x - x_i) / (x_i - x_j)
+
+    The encapsulating `interpolate` function sums these terms to construct
+    the final interpolated polynomial.
+
     Arguments:
       - points: a list of (float, float)
       - i: an integer indexing a specific point
+
+    Returns:
+      A Polynomial instance containing the desired product.
     """
     theTerm = Polynomial([1.])
     xi, yi = points[i]
@@ -17,8 +28,22 @@ def single_term(points, i):
             continue
 
         xj = p[0]
+
+        """
+        The inlined Polynomial instance below is how we represent 
+        
+          (x - x_i) / (x_i - x_j) 
+        
+        using our Polynomial data type (where t is the variable, and
+        x_i, x_j are two x-values of data points):
+        
+          (x - x_i) / (x_i - x_j) = (-x_j / (x_i - x_j)) * t^0 
+                                  +    (1 / (x_i - x_j)) * t^1
+        """
         theTerm = theTerm * Polynomial([-xj / (xi - xj), 1.0 / (xi - xj)])
 
+    # Polynomial([yi]) is a constant polynomial, i.e., we're scaling theTerm 
+    # by a constant.
     return theTerm * Polynomial([yi])