Index: test/autovacuum.test
==================================================================
--- test/autovacuum.test
+++ test/autovacuum.test
@@ -9,42 +9,60 @@
 #
 #***********************************************************************
 # This file implements regression tests for SQLite library.  The
 # focus of this file is testing the SELECT statement.
 #
-# $Id: autovacuum.test,v 1.3 2004/11/03 03:01:17 danielk1977 Exp $
+# $Id: autovacuum.test,v 1.4 2004/11/03 09:30:55 danielk1977 Exp $
 
 set testdir [file dirname $argv0]
 source $testdir/tester.tcl
 
+# Return a string $len characters long. The returned string is $char repeated
+# over and over. For example, [make_str abc 8] returns "abcabcab".
 proc make_str {char len} {
   set str [string repeat $char. $len]
   return [string range $str 0 [expr $len-1]]
 }
 
+# Return the number of pages in the file test.db by looking at the file system.
 proc file_pages {} {
   return [expr [file size test.db] / 1024]
 }
+
+# Test cases autovacuum-1.* work as follows:
+#
+# 1. A table with a single indexed field is created.
+# 2. Approximately 20 rows are inserted into the table. Each row is long 
+#    enough such that it uses at least 2 overflow pages for both the table 
+#    and index entry.
+# 3. The rows are deleted in a psuedo-random order. Sometimes only one row
+#    is deleted per transaction, sometimes more than one.
+# 4. After each transaction the table data is checked to ensure it is correct
+#    and a "PRAGMA integrity_check" is executed.
+# 5. Once all the rows are deleted the file is checked to make sure it 
+#    consists of exactly 4 pages.
+#
+# Steps 2-5 are repeated for a few different psuedo-random delete patterns 
+# (defined by the $delete_orders list).
+set delete_orders [list]
+lappend delete_orders {1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20}
+lappend delete_orders {20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1} 
+lappend delete_orders {8 18 2 4 14 11 13 3 10 7 9 5 12 17 19 15 20 6 16 1}
+lappend delete_orders {10 3 11 17 19 20 7 4 13 6 1 14 16 12 9 18 8 15 5 2}
+lappend delete_orders {{1 2 3 4 5 6 7 8 9 10} {11 12 13 14 15 16 17 18 19 20}}
+lappend delete_orders {{19 8 17 15} {16 11 9 14} {18 5 3 1} {13 20 7 2} {6 12}}
+
+# The length of each table entry. 
+set ENTRY_LEN 3500
 
 do_test autovacuum-1.1 {
   execsql {
     CREATE TABLE av1(a);
     CREATE INDEX av1_idx ON av1(a);
   }
 } {}
 
-set ENTRY_LEN 3000
-
-set delete_orders [list]
-lappend delete_orders {1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20}
-lappend delete_orders {20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1} 
-lappend delete_orders {8 18 2 4 14 11 13 3 10 7 9 5 12 17 19 15 20 6 16 1}
-lappend delete_orders {10 3 11 17 19 20 7 4 13 6 1 14 16 12 9 18 8 15 5 2}
-lappend delete_orders {{1 2 3 4 5 6 7 8 9 10} {11 12 13 14 15 16 17 18 19 20}}
-lappend delete_orders \
-        {{19 8 17 15} {16 11 9 14} {18 5 3 1} {13 20 7 2} {6 12 4 10}}
-
 set tn 0
 foreach delete_order $delete_orders {
   incr tn
 
   # Set up the table.
@@ -52,29 +70,33 @@
   foreach i [lsort -integer [eval concat $delete_order]] {
     execsql "INSERT INTO av1 (oid, a) VALUES($i, '[make_str $i $ENTRY_LEN]')"
     lappend ::tbl_data [make_str $i $ENTRY_LEN]
   }
 
+  # Make sure the integrity check passes with the initial data.
   do_test autovacuum-1.$tn.1 {
     execsql {
       pragma integrity_check
     }
   } {ok}
 
   foreach delete $delete_order {
+    # Delete one set of rows from the table.
     do_test autovacuum-1.$tn.($delete).1 {
       execsql "
         DELETE FROM av1 WHERE oid IN ([join $delete ,])
       "
     } {}
 
+    # Do the integrity check.
     do_test autovacuum-1.$tn.($delete).2 {
       execsql {
         pragma integrity_check
       }
     } {ok}
 
+    # Ensure the data remaining in the table is what was expected.
     foreach d $delete {
       set idx [lsearch $::tbl_data [make_str $d $ENTRY_LEN]]
       set ::tbl_data [lreplace $::tbl_data $idx $idx]
     }
     do_test autovacuum-1.$tn.($delete).3 {
@@ -82,12 +104,13 @@
         select a from av1
       }
     } $::tbl_data
   }
 
+  # All rows have been deleted. Ensure the file has shrunk to 4 pages.
   do_test autovacuum-1.$tn.3 {
     file_pages
   } {4}
 }
 
 finish_test