add test comments

jstests/capped6.js

@@ -1,3 +1,5 @@
+// Test NamespaceDetails::cappedTruncateAfter via 'captrunc' command
+
 Random.setRandomSeed();
 
 db.capped6.drop();
@@ -8,6 +10,12 @@ function debug( x ) {
 //    print( x );
 }
 
+/**
+ * Check that documents in the collection are in order according to the value
+ * of a, which corresponds to the insert order.  This is a check that the oldest
+ * document(s) is/are deleted when space is needed for the newest document.  The
+ * check is performed in both forward and reverse directions.
+ */
 function checkOrder( i ) {
     res = tzz.find().sort( { $natural: -1 } );
     assert( res.hasNext(), "A" );
@@ -30,12 +38,18 @@ function checkOrder( i ) {
 var val = new Array( 500 );
 var c = "";
 for( i = 0; i < 500; ++i, c += "-" ) {
+    // The a values are strings of increasing length.
     val[ i ] = { a: c };
 }
 
 var oldMax = Random.randInt( 500 );
 var max = 0;
 
+/**
+ * Insert new documents until there are 'oldMax' documents in the collection,
+ * then remove a random number of documents (often all but one) via one or more
+ * 'captrunc' requests.
+ */
 function doTest() {
     for( var i = max; i < oldMax; ++i ) {
         tzz.save( val[ i ] );
@@ -48,7 +62,13 @@ function doTest() {
         min = Random.randInt( count ) + 1;
     }
 
+    // Iteratively remove a random number of documents until we have no more
+    // than 'min' documents.
     while( count > min ) {
+        // 'n' is the number of documents to remove - we must account for the
+        // possibility that 'inc' will be true, and avoid removing all documents
+        // from the collection in that case, as removing all documents is not
+        // allowed by 'captrunc'
         var n = Random.randInt( count - min - 1 ); // 0 <= x <= count - min - 1
         var inc = Random.rand() > 0.5;
         debug( count + " " + n + " " + inc );
@@ -58,10 +78,13 @@ function doTest() {
         }
         count -= n;
         max -= n;
+        // Validate the remaining documents.
         checkOrder( max - 1 );
     }
 }
 
+// Repeatedly add up to 'oldMax' documents and then truncate the newest
+// documents.  Newer documents take up more space than older documents.
 for( var i = 0; i < 10; ++i ) {
     doTest();
 }
@@ -77,6 +100,8 @@ db.capped6.drop();
 db._dbCommand( { create: "capped6", capped: true, size: 1000, $nExtents: 11, autoIndexId: false } );
 tzz = db.capped6;
 
+// Same test as above, but now the newer documents take less space than the
+// older documents instead of more.
 for( var i = 0; i < 10; ++i ) {
     doTest();
 }

jstests/capped7.js

@@ -1,3 +1,5 @@
+// Test NamespaceDetails::emptyCappedCollection via 'emptycapped' command
+
 Random.setRandomSeed();
 
 db.capped7.drop();
@@ -8,6 +10,10 @@ var ten = new Array( 11 ).toString().replace( /,/g, "-" );
 
 count = 0;
 
+/**
+ * Insert new documents until the capped collection loops and the document
+ * count doesn't increase on insert.
+ */
 function insertUntilFull() {
 count = tzz.count();
     var j = 0;
@@ -23,21 +29,27 @@ while( 1 ) {
 
 insertUntilFull();
 
+// oldCount == count before empty
 oldCount = count;
 
 assert.eq.automsg( "11", "tzz.stats().numExtents" );
+
+// oldSize == size before empty
 var oldSize = tzz.stats().storageSize;
 
 assert.commandWorked( db._dbCommand( { emptycapped: "capped7" } ) );
 
+// check that collection storage parameters are the same after empty
 assert.eq.automsg( "11", "tzz.stats().numExtents" );
 assert.eq.automsg( "oldSize", "tzz.stats().storageSize" );
 
+// check that the collection is empty after empty
 assert.eq.automsg( "0", "tzz.find().itcount()" );
 assert.eq.automsg( "0", "tzz.count()" );
 
+// check that we can reuse the empty collection, inserting as many documents
+// as we were able to the first time through.
 insertUntilFull();
-
 assert.eq.automsg( "oldCount", "count" );
 assert.eq.automsg( "oldCount", "tzz.find().itcount()" );
 assert.eq.automsg( "oldCount", "tzz.count()" );
@@ -47,12 +59,16 @@ var oldSize = tzz.stats().storageSize;
 
 assert.commandWorked( db._dbCommand( { emptycapped: "capped7" } ) );
 
+// check that the collection storage parameters are unchanged after another empty
 assert.eq.automsg( "11", "tzz.stats().numExtents" );
 assert.eq.automsg( "oldSize", "tzz.stats().storageSize" );
 
+// insert an arbitrary number of documents
 var total = Random.randInt( 2000 );
 for( var j = 1; j <= total; ++j ) {
     tzz.save( {i:ten,j:j} );
+    // occasionally check that only the oldest documents are removed to make room
+    // for the newest documents
     if ( Random.rand() > 0.95 ) {
         assert.automsg( "j >= tzz.count()" );
         assert.eq.automsg( "tzz.count()", "tzz.find().itcount()" );
@@ -62,6 +78,7 @@ for( var j = 1; j <= total; ++j ) {
         while( c.hasNext() ) {
             assert.eq.automsg( "c.next().j", "k--" );
         }
+        // check the same thing with a reverse iterator as well
         var c = tzz.find().sort( {$natural:1} );
         assert.automsg( "c.hasNext()" );
         while( c.hasNext() ) {