Comment what the logic in uploadKeys does

lib/crypto/index.js

@@ -153,18 +153,43 @@ Crypto.prototype.getDeviceEd25519Key = function() {
 Crypto.prototype.uploadKeys = function(maxKeys) {
     var self = this;
     return _uploadDeviceKeys(this).then(function(res) {
+        // We need to keep a pool of one time public keys on the server so that
+        // other devices can start conversations with us. But we can only store
+        // a finite number of private keys in the olm Account object.
+        // To complicate things further then can be a delay between a device
+        // claiming a public one time key from the server and it sending us a
+        // message. We need to keep the corresponding private key locally until
+        // we receive the message.
+        // But that message might never arrive leaving us stuck with duff
+        // private keys clogging up our local storage.
+        // So we need some kind of enginering compromise to balance all of
+        // these factors.
+
+        // We first find how many keys the server has for us.
         var keyCount = res.one_time_key_counts.curve25519 || 0;
+        // We then check how many keys we can store in the Account object.
         var maxOneTimeKeys = self._olmDevice.maxNumberOfOneTimeKeys();
+        // Try to keep at most half that number on the server. This leaves the
+        // rest of the slots free to hold keys that have been cliamed from the
+        // server but we haven't recevied a message for.
         var keyLimit = Math.floor(maxOneTimeKeys / 2);
+        // We work out how many new keys we need to create to top up the server
+        // If there are too many keys on the server then we don't need to
+        // create any more keys.
         var numberToGenerate = Math.max(keyLimit - keyCount, 0);
         if (maxKeys !== undefined) {
+            // Creating keys can be an expensive operation so we limit the
+            // number we generate in one go to avoid blocking the application
+            // for too long.
             numberToGenerate = Math.min(numberToGenerate, maxKeys);
         }
 
         if (numberToGenerate <= 0) {
+            // If we don't need to generate any keys then we are done.
             return;
         }
 
+        // Ask olm to generate new one time keys, then upload them to synapse.
         self._olmDevice.generateOneTimeKeys(numberToGenerate);
         return _uploadOneTimeKeys(self);
     });