more documentation

src/ecdsa/ellipticcurve.py

@@ -78,8 +78,21 @@ def __str__(self):
 
 
 class PointJacobi(object):
-  """Point on an elliptic curve. Uses Jacobi representation"""
+  """
+  Point on an elliptic curve. Uses Jacobi representation
+
+  In Jacobian coordinates, there are three parameters, X, Y and Z.
+  They correspond to Weierstrass representation points 'x' and 'y' like so:
+
+  x = X / Z²
+  y = Y / Z³
+  """
   def __init__(self, curve, x, y, z, order=None, generator=False):
+      """
+      :param bool generator: the point provided is a curve generator, as
+        such, it will be commonly used with scalar multiplication. This will
+        cause to precompute multiplication table for it
+      """
       self.__curve = curve
       self.__x = x
       self.__y = y
@@ -106,19 +119,31 @@ def curve(self):
       return self.__curve
 
   def x(self):
-      """Return x coordinate in Weierstrass form"""
+      """
+      Return x coordinate in Weierstrass form.
+
+      This method should be used only when the 'y' coordinate is not needed.
+      It's computationally more efficient to use `to_weierstrass()` and then
+      call x() and y() on the returned instance.
+      """
       p = self.__curve.p()
       z = numbertheory.inverse_mod(self.__z, p)
       return self.__x * z**2 % p
 
   def y(self):
-      """Return y coordinate in Weierstrass form"""
+      """
+      Return y coordinate in Weierstrass form.
+
+      This method should be used only when the 'x' coordinate is not needed.
+      It's computationally more efficient to use `to_weierstrass()` and then
+      call x() and y() on the returned instance.
+      """
       p = self.__curve.p()
       z = numbertheory.inverse_mod(self.__z, p)
       return self.__y * z**3 % p
 
   def normalise(self):
-      """Return point with z == 1."""
+      """Return point scaled so that z == 1."""
       if self.__z == 1:
           return self
       return self.from_weierstrass(self.to_weierstrass())