Document race condition test fix

Author: Alec Gibson

test/client/submit.js

@@ -519,16 +519,28 @@ describe('client submit', function() {
         if (err) return done(err);
         var docCallback;
         var doc2Callback;
+        // The submit retry happens just after an op is committed. This hook into the middleware
+        // catches both ops just before they're about to be committed. This ensures that both ops
+        // are certainly working on the same snapshot (ie one op hasn't been committed before the
+        // other fetches the snapshot to apply to). By storing the callbacks, we can then
+        // manually trigger the callbacks, first calling doc, and when we know that's been committed,
+        // we then commit doc2.
         backend.use('commit', function (request, callback) {
           if (request.op.op[0].na === 2) docCallback = callback;
           if (request.op.op[0].na === 7) doc2Callback = callback;
 
+          // Wait until both ops have been applied to the same snapshot and are about to be committed
           if (docCallback && doc2Callback) {
+            // Trigger the first op's commit and then the second one later, which will cause the
+            // second op to retry
             docCallback();
           }
         });
         doc.submitOp({p: ['age'], na: 2}, function (error) {
           if (error) return done(error);
+          // When we know the first op has been committed, we try to commit the second op, which will
+          // fail because it's working on an out-of-date snapshot. It will retry, but exceed the
+          // maxSubmitRetries limit of 0
           doc2Callback();
         });
         doc2.submitOp({p: ['age'], na: 7}, function (error) {