SHOW EXPLAIN: better comments

sql/my_apc.h

@@ -75,38 +75,19 @@ private:
   */
   Call_request *apc_calls;
  
-
-  /*
-    This mutex is used to
-    - make queue put/remove operations atomic (one must be in posession of the
-      mutex when putting/removing something from the queue)
-
-    - make sure that nobody enqueues a request onto an Apc_target which has 
-      disabled==TRUE. The idea is:
-      = requestor must be in possession of the mutex and check that
-        disabled==FALSE when he is putting his request into the queue.
-      = When the owner (ie. service) thread changes the Apc_target from 
-        enabled to disabled, it will acquire the mutex, disable the 
-        Apc_target (preventing any new requests), and then serve all pending 
-        requests. 
-      That way, we will never have the situation where the Apc_target is 
-      disabled, but there are some un-served requests.
-  */
-  //pthread_mutex_t LOCK_apc_queue;
-
   class Call_request
   {
   public:
     apc_func_t func; /* Function to call */
     void *func_arg;  /* Argument to pass it */
-    bool processed;
 
-    //pthread_mutex_t LOCK_request;
-    //pthread_cond_t COND_request;
+    /* The caller will actually wait for "processed==TRUE" */
+    bool processed;
 
     /* Condition that will be signalled when the request has been served */
     mysql_cond_t COND_request;
-
+    
+    /* Double linked-list linkage */
     Call_request *next;
     Call_request *prev;
     

sql/sql_class.cc

@@ -2311,6 +2311,10 @@ int select_send::send_data(List<Item> &items)
 
 //////////////////////////////////////////////////////////////////////////////
 
+/*
+  Save the data being sent in our internal buffer.
+*/
+
 int select_result_explain_buffer::send_data(List<Item> &items)
 {
   List_iterator_fast<Item> li(items);
@@ -2357,7 +2361,7 @@ int select_result_explain_buffer::send_data(List<Item> &items)
 }
 
 
-/* Write all strings out to the output, and free them. */
+/* Write the saved resultset to the client (via this->protocol) and free it. */
 
 void select_result_explain_buffer::flush_data()
 {
@@ -2373,7 +2377,7 @@ void select_result_explain_buffer::flush_data()
 }
 
 
-/* Just free all of the accumulated strings */
+/* Free the accumulated resultset */
 
 void select_result_explain_buffer::discard_data()
 {

sql/sql_class.h

@@ -1522,16 +1522,29 @@ extern "C" void my_message_sql(uint error, const char *str, myf MyFlags);
 
 class select_result_explain_buffer;
 
+
+/*
+  SHOW EXPLAIN request object. 
+  
+  The thread that runs SHOW EXPLAIN statement creates a Show_explain_request
+  object R, and then schedules APC call of
+  Show_explain_request::get_explain_data((void*)&R).
+
+*/
+
 class Show_explain_request
 {
 public:
-  THD *target_thd;
-  THD *request_thd;
+  THD *target_thd;  /* thd that we're running SHOW EXPLAIN for */
+  THD *request_thd; /* thd that run SHOW EXPLAIN command */
   
+  /* If true, there was some error when producing EXPLAIN output. */
   bool failed_to_produce;
-  
+   
+  /* SHOW EXPLAIN will be stored here */
   select_result_explain_buffer *explain_buf;
-
+  
+  /* Query that we've got SHOW EXPLAIN for */
   String query_str;
 
   static void get_explain_data(void *arg);
@@ -2414,11 +2427,11 @@ public:
 
 
   /*
-    This is what allows this thread to serve as a target for others to 
-    schedule Async Procedure Calls on.
+    Allows this thread to serve as a target for others to schedule Async 
+    Procedure Calls on.
 
-    It's possible to schedule arbitrary C function call but currently this
-    facility is used only by SHOW EXPLAIN code (See Show_explain_request)
+    It's possible to schedule arbitrary C++ function calls. Currently, only
+    Show_explain_request uses this.
   */
   Apc_target apc_target;