Add some comments to securepair

lib/securepair.js

@@ -215,11 +215,18 @@ SecurePair.prototype._cycle = function () {
   var chunk = null;
   var pool = null;
 
+  // Pull in incoming encrypted data from the socket.
+  // This arrives via some code like this:
+  //
+  //   socket.on('data', function (d) {
+  //     pair.encrypted.write(d)
+  //   });
+  //
   while (this._encInPending.length > 0) {
     tmp = this._encInPending.shift();
 
     try {
-      debug('writng from encIn');
+      debug('writing from encIn');
       rv = this._ssl.encIn(tmp, 0, tmp.length);
     } catch (e) {
       return this._error(e);
@@ -233,6 +240,11 @@ SecurePair.prototype._cycle = function () {
     assert(rv === tmp.length);
   }
 
+  // Pull in any clear data coming from the application.
+  // This arrives via some code like this:
+  //
+  //   pair.cleartext.write("hello world");
+  //
   while (this._clearInPending.length > 0) {
     tmp = this._clearInPending.shift();
     try {
@@ -280,6 +292,9 @@ SecurePair.prototype._cycle = function () {
     } while (checker(bytesRead));
   }
 
+  // Move decryptoed, clear data out into the application.
+  // From the user's perspective this occurs as a 'data' event
+  // on the pair.cleartext.
   mover(
     function (pool, offset, length) {
       debug('reading from clearOut');
@@ -292,6 +307,14 @@ SecurePair.prototype._cycle = function () {
       return bytesRead > 0 && self._cleartextWriteState === true;
     });
 
+  // Move encrypted data to the stream. From the user's perspective this
+  // occurs as a 'data' event on the pair.encrypted. Usually the application
+  // will have some code which pipes the stream to a socket:
+  //
+  //   pair.encrypted.on('data', function (d) {
+  //     socket.write(d);
+  //   });
+  //
   mover(
     function (pool, offset, length) {
       debug('reading from encOut');