From: Brian Warner <warner@lothar.com>
Date: Wed, 13 Jan 2010 00:42:26 +0000 (-0800)
Subject: client.py: fix/update comments on KeyGenerator
X-Git-Url: https://git.rkrishnan.org/frontends/webapi.rst?a=commitdiff_plain;h=fb879ddea40c03e764d3c42ca76a50df6ed5825b;p=tahoe-lafs%2Ftahoe-lafs.git

client.py: fix/update comments on KeyGenerator
---

diff --git a/src/allmydata/client.py b/src/allmydata/client.py
index 7bab5577..ec079762 100644
--- a/src/allmydata/client.py
+++ b/src/allmydata/client.py
@@ -52,6 +52,10 @@ class SecretHolder:
         return self._convergence_secret
 
 class KeyGenerator:
+    """I create RSA keys for mutable files. Each call to generate() returns a
+    single keypair. The keysize is specified first by the keysize= argument
+    to generate(), then with a default set by set_default_keysize(), then
+    with a built-in default of 2048 bits."""
     def __init__(self):
         self._remote = None
         self.default_keysize = 2048
@@ -60,11 +64,20 @@ class KeyGenerator:
         self._remote = keygen
     def set_default_keysize(self, keysize):
         """Call this to override the size of the RSA keys created for new
-        mutable files. The default of None means to let mutable.filenode
-        choose its own size, which means 2048 bits."""
+        mutable files which don't otherwise specify a size. This will affect
+        all subsequent calls to generate() without a keysize= argument. The
+        default size is 2048 bits. Test cases should call this method once
+        during setup, to cause me to create smaller (522 bit) keys, so the
+        unit tests run faster."""
         self.default_keysize = keysize
 
     def generate(self, keysize=None):
+        """I return a Deferred that fires with a (verifyingkey, signingkey)
+        pair. I accept a keysize in bits (522 bit keys are fast for testing,
+        2048 bit keys are standard). If you do not provide a keysize, I will
+        use my default, which is set by a call to set_default_keysize(). If
+        set_default_keysize() has never been called, I will create 2048 bit
+        keys."""
         keysize = keysize or self.default_keysize
         if self._remote:
             d = self._remote.callRemote('get_rsa_key_pair', keysize)