Better comments

sql/sql_select.cc

@@ -19084,7 +19084,15 @@ end_send(JOIN *join, JOIN_TAB *join_tab __attribute__((unused)),
 }
 
 
-	/* ARGSUSED */
+/*
+  @brief
+    Perform a GROUP BY operation over a stream of rows ordered by their group. The 
+    result is sent into join->result.
+
+  @detail
+    Also applies HAVING, etc.
+*/
+
 enum_nested_loop_state
 end_send_group(JOIN *join, JOIN_TAB *join_tab __attribute__((unused)),
 	       bool end_of_records)
@@ -19260,8 +19268,17 @@ end_write(JOIN *join, JOIN_TAB *join_tab __attribute__((unused)),
   DBUG_RETURN(NESTED_LOOP_OK);
 }
 
-/* ARGSUSED */
-/** Group by searching after group record and updating it if possible. */
+
+/*
+  @brief
+    Perform a GROUP BY operation over rows coming in arbitrary order. 
+    
+    This is done by looking up the group in a temp.table and updating group
+    values.
+
+  @detail
+    Also applies HAVING, etc.
+*/
 
 static enum_nested_loop_state
 end_update(JOIN *join, JOIN_TAB *join_tab __attribute__((unused)),
@@ -19391,7 +19408,17 @@ end_unique_update(JOIN *join, JOIN_TAB *join_tab __attribute__((unused)),
 }
 
 
-	/* ARGSUSED */
+/*
+  @brief
+    Perform a GROUP BY operation over a stream of rows ordered by their group.
+    Write the result into a temporary table.
+
+  @detail
+    Also applies HAVING, etc.
+
+    The rows are written into temptable so e.g. filesort can read them.
+*/
+
 enum_nested_loop_state
 end_write_group(JOIN *join, JOIN_TAB *join_tab __attribute__((unused)),
 		bool end_of_records)

sql/sql_select.h

@@ -1039,7 +1039,20 @@ class JOIN :public Sql_alloc
   table_map outer_join;
   /* Bitmap of tables used in the select list items */
   table_map select_list_used_tables;
-  ha_rows  send_records,found_records,examined_rows,row_limit, select_limit;
+  ha_rows  send_records,found_records,examined_rows;
+
+  /*
+    LIMIT for the JOIN operation. When not using aggregation or DISITNCT, this 
+    is the same as select's LIMIT clause specifies.
+    Note that this doesn't take sql_calc_found_rows into account.
+  */
+  ha_rows row_limit;
+
+  /*
+    How many output rows should be produced after GROUP BY.
+    (if sql_calc_found_rows is used, LIMIT is ignored)
+  */
+  ha_rows select_limit;
   /**
     Used to fetch no more than given amount of rows per one
     fetch operation of server side cursor.
@@ -1048,8 +1061,10 @@ class JOIN :public Sql_alloc
       - fetch_limit= HA_POS_ERROR if there is no cursor.
       - when we open a cursor, we set fetch_limit to 0,
       - on each fetch iteration we add num_rows to fetch to fetch_limit
+    NOTE: currently always HA_POS_ERROR.
   */
   ha_rows  fetch_limit;
+
   /* Finally picked QEP. This is result of join optimization */
   POSITION *best_positions;