Index: /trunk/ippTools/share/stacktool_definebyquery_insert.sql
===================================================================
--- /trunk/ippTools/share/stacktool_definebyquery_insert.sql	(revision 18576)
+++ /trunk/ippTools/share/stacktool_definebyquery_insert.sql	(revision 18577)
@@ -1,6 +1,7 @@
+-- Define the inputs to a defined stack
 INSERT INTO
         stackInputSkyfile(stack_id, warp_id)
 SELECT
-        @STACK_ID@,
+        @STACK_ID@, -- This should be replaced with the stack_id
         warp_id
 FROM warpSkyfile
Index: /trunk/ippTools/share/stacktool_definebyquery_insert_random.sql
===================================================================
--- /trunk/ippTools/share/stacktool_definebyquery_insert_random.sql	(revision 18576)
+++ /trunk/ippTools/share/stacktool_definebyquery_insert_random.sql	(revision 18577)
@@ -1,28 +1,32 @@
+-- Use a random set of warps for the inputs to a defined stack
 INSERT INTO
         stackInputSkyfile(stack_id, warp_id)
 SELECT
-        @STACK_ID@,
+        @STACK_ID@, -- This should be replaced with the stack_id
         warp_id
 FROM (
-SELECT
-        warpSkyfile.*,
-        rand() AS rnd_num
-FROM warpSkyfile
-JOIN warpRun
-    USING(warp_id, tess_id)
-JOIN fakeRun
-    USING(fake_id, tess_id)
-JOIN camRun
-    USING(cam_id, tess_id)
-JOIN chipRun
-    USING(chip_id, tess_id)
-JOIN rawExp
-    USING(exp_id, tess_id)
-WHERE
-    skycell_id = '%s'
-    AND tess_id = '%s'
-    AND rawExp.filter = '%s'
-    AND warpSkyfile.fault = 0
-ORDER BY rnd_num
-LIMIT %d
+    -- Sub-select to get the random set of warps
+    SELECT
+            warpSkyfile.*,
+            rand() AS rnd_num
+    FROM warpSkyfile
+    JOIN warpRun
+        USING(warp_id, tess_id)
+    JOIN fakeRun
+        USING(fake_id, tess_id)
+    JOIN camRun
+        USING(cam_id, tess_id)
+    JOIN chipRun
+        USING(chip_id, tess_id)
+    JOIN rawExp
+        USING(exp_id, tess_id)
+    WHERE
+        skycell_id = '%s'
+        AND tess_id = '%s'
+        AND rawExp.filter = '%s'
+        AND warpSkyfile.fault = 0
+    -- Sort by the random number, and take the first N
+    -- to get a random set of N.
+    ORDER BY rnd_num
+    LIMIT %d
 ) AS randomWarps
Index: /trunk/ippTools/share/stacktool_definebyquery_select.sql
===================================================================
--- /trunk/ippTools/share/stacktool_definebyquery_select.sql	(revision 18576)
+++ /trunk/ippTools/share/stacktool_definebyquery_select.sql	(revision 18577)
@@ -1,2 +1,7 @@
+-- This is the SELECT part of the query to get a list of skycells with
+-- warps that are ready to be stacked, along with the numbers of warps
+-- ready to be stacked and already in stacks.  It needs to be
+-- completed by a GROUP BY statement (see below).
+
 SELECT
     warpSkyfile.skycell_id,
@@ -4,6 +9,6 @@
     stackRun.stack_id,
     rawExp.filter,
-    COUNT(warpSkyfile.skycell_id) AS num_avail,
-    COUNT(stackRun.stack_id) AS num_extant
+    COUNT(warpSkyfile.skycell_id) AS num_avail, -- number available to be stacked
+    COUNT(stackRun.stack_id) AS num_extant -- number already in the stack
 FROM warpRun
 JOIN warpSkyfile 
@@ -28,3 +33,3 @@
     AND warpSkyfile.fault = 0
 -- Here should follow the SQL in stacktool_definebyquery_groupby.sql,
--- after additional WHERE conditions have been added
+-- after any additional WHERE conditions have been added