Added documentation, fixed some minor bugs/typos

db_create.php

@@ -42,6 +42,9 @@ if (! $result) {
     $GLOBALS['db'] = '';
     $GLOBALS['table'] = '';
 
+    /**
+     * If in an Ajax request, just display the message with {@link PMA_ajaxResponse}
+     */
     if($GLOBALS['is_ajax_request'] == true) {
         PMA_ajaxResponse($message, FALSE);
     }
@@ -53,29 +56,55 @@ if (! $result) {
     $message->addParam($new_db);
     $GLOBALS['db'] = $new_db;
 
+    /**
+     * If in an Ajax request, build the output and send it
+     */
     if($GLOBALS['is_ajax_request'] == true) {
 
+        /**
+         * String containing the SQL Query formatted in pretty HTML
+         * @global array $GLOBALS['extra_data']
+         * @name $extra_data 
+         */
         $extra_data['sql_query'] = PMA_showMessage(NULL, $sql_query, 'success');
 
         //Construct the html for the new database, so that it can be appended to the list of databases on server_databases.php
 
+        /**
+         * Build the array to be passed to {@link PMA_generate_common_url} to generate the links
+         * @global array $GLOBALS['db_url_params']
+         * @name $db_url_params 
+         */
         $db_url_params['db'] = $new_db;
 
         $is_superuser = PMA_isSuperuser();
 
+        /**
+         * String that will contain the output HTML
+         * @name    $new_db_string
+         */
         $new_db_string = '<tr>';
 
+        /**
+         * Is user allowed to drop the database?
+         */
         if ($is_superuser || $cfg['AllowUserDropDatabase']) {
             $new_db_string .= '<td class="tool">';
-            $new_db_string .= '<input type="checkbox" title="'. $new_db .'" value="' . $new_db . '" name="selected_dbsp[]" />';
+            $new_db_string .= '<input type="checkbox" title="'. $new_db .'" value="' . $new_db . '" name="selected_dbs[]" />';
             $new_db_string .='</td>';
         }
 
+        /**
+         * Link to the database's page
+         */
         $new_db_string .= '<td class="name">';
         $new_db_string .= '<a target="_parent" title="Jump to database" href="index.php' . PMA_generate_common_url($db_url_params) . '">';
         $new_db_string .= $new_db . '</a>';
         $new_db_string .= '</td>';
 
+        /**
+         * If the user has privileges, let him check privileges for the DB
+         */
         if($is_superuser) {
             
             $db_url_params['checkprivs'] = $new_db;
@@ -90,6 +119,8 @@ if (! $result) {
 
         $new_db_string .= '</tr>';
 
+        /** @todo Statistics for newly created DB! */
+
         $extra_data['new_db_string'] = $new_db_string;
 
         PMA_ajaxResponse($message, true, $extra_data);

db_operations.php

@@ -263,6 +263,10 @@ if (strlen($db) && (! empty($db_rename) || ! empty($db_copy))) {
         }
     }
 
+    /**
+     * Database has been successfully renamed/moved.  If in an Ajax request, 
+     * generate the output with {@link PMA_ajaxResponse} and exit
+     */
     if( $GLOBALS['is_ajax_request'] == true) {
         $extra_data['newname'] = $newname;
         $extra_data['sql_query'] = PMA_showMessage(NULL, $sql_query);

db_search.php

@@ -111,7 +111,7 @@ if (empty($_REQUEST['field_str']) || ! is_string($_REQUEST['field_str'])) {
 }
 
 /**
- * Displays top links
+ * Displays top links if we are not in an Ajax request
  */
 $sub_part = '';
 
@@ -275,6 +275,9 @@ if (isset($_REQUEST['submit_search'])) {
     }
 } // end 1.
 
+/**
+ * If we are in an Ajax request, we need to exit after displaying all the HTML
+ */
 if($GLOBALS['is_ajax_request'] == true) {
     exit;
 }

db_tracking.php

@@ -9,9 +9,12 @@
  */
 require_once './libraries/common.inc.php';
 
-//Get some js files needed for Ajax
+//Get some js files needed for Ajax requests
 $GLOBALS['js_include'][] = 'jquery/jquery-ui-1.8.custom.js';
 
+/**
+ * If we are not in an Ajax request, then do the common work and show the links etc.
+ */
 if($GLOBALS['is_ajax_request'] != true) {
     require './libraries/db_common.inc.php';
 }
@@ -26,6 +29,10 @@ require './libraries/db_info.inc.php';
 if (isset($_REQUEST['delete_tracking']) && isset($_REQUEST['table'])) {
     PMA_Tracker::deleteTracking($GLOBALS['db'], $_REQUEST['table']);
 
+    /**
+     * If in an Ajax request, generate the success message and use 
+     * {@link PMA_ajaxResponse()} to send the output
+     */
     if($GLOBALS['is_ajax_request'] == true) {
         $message = PMA_Message::success();
         PMA_ajaxResponse($message, true);

js/functions.js

@@ -1757,6 +1757,10 @@ function PMA_ajaxShowMessage(message, timeout) {
         return true;
     }
 
+    /**
+     * @var msg String containing the message that has to be displayed
+     * @default PMA_messages['strLoading']
+     */
     if(!message) {
         var msg = PMA_messages['strLoading'];
     }
@@ -1764,6 +1768,10 @@ function PMA_ajaxShowMessage(message, timeout) {
         var msg = message;
     }
 
+    /**
+     * @var timeout Number of milliseconds for which {@link msg} will be visible
+     * @default 5000 ms
+     */
     if(!timeout) {
         var to = 5000;
     }
@@ -1772,6 +1780,7 @@ function PMA_ajaxShowMessage(message, timeout) {
     }
 
     if( !ajax_message_init) {
+        //For the first time this function is called, append a new div
         $(function(){
             $('<div id="loading_parent"></div>')
             .insertBefore("#serverinfo");
@@ -1790,6 +1799,7 @@ function PMA_ajaxShowMessage(message, timeout) {
         ajax_message_init = true;
     }
     else {
+        //Otherwise, just show the div again after inserting the message
         $("#loading")
         .clearQueue()
         .html(msg)
@@ -1804,7 +1814,8 @@ function PMA_ajaxShowMessage(message, timeout) {
 }
 
 /**
- * jQuery function that uses jQueryUI's dialogs to confirm with user
+ * jQuery function that uses jQueryUI's dialogs to confirm with user. Does not
+ *  return a jQuery object yet and hence cannot be chained
  *
  * @param   string      question
  * @param   string      url         URL to be passed to the callbackFn to make
@@ -1817,6 +1828,10 @@ jQuery.fn.PMA_confirm = function(question, url, callbackFn) {
         return true;
     }
 
+    /**
+     *  @var    button_options  Object that stores the options passed to jQueryUI
+     *                          dialog
+     */
     var button_options = {};
     button_options[PMA_messages['strOK']] = function(){
                                                 $(this).dialog("close").remove();
@@ -1837,11 +1852,19 @@ jQuery.fn.PMA_confirm = function(question, url, callbackFn) {
  * Also fixes the even/odd classes of the table rows at the end.
  *
  * @param   string      text_selector   string to select the sortKey's text
+ *
+ * @return  jQuery Object for chaining purposes
  */
 jQuery.fn.PMA_sort_table = function(text_selector) {
     return this.each(function() {
+
+        /**
+         * @var table_body  Object referring to the table's <tbody> element
+         */
         var table_body = $(this);
-        //collect all rows
+        /**
+         * @var rows    Object referring to the collection of rows in {@link table_body}
+         */
         var rows = $(this).find('tr').get();
 
         //get the text of the field that we will sort by
@@ -1860,7 +1883,7 @@ jQuery.fn.PMA_sort_table = function(text_selector) {
             return 0;
         })
 
-        //pull out each row from the table and then append it according to it's order'
+        //pull out each row from the table and then append it according to it's order
         $.each(rows, function(index, row) {
             $(table_body).append(row);
             row.sortKey = null;
@@ -1879,15 +1902,26 @@ jQuery.fn.PMA_sort_table = function(text_selector) {
  * jQuery coding for 'Create Table'.  Used on db_operations.php,
  * db_structure.php and db_tracking.php (i.e., wherever
  * libraries/display_create_table.lib.php is used)
+ * 
+ * Attach Ajax Event handlers for Create Table
  */
 $(document).ready(function() {
 
-    //make Ajax call and create the dialog with the full create table form
+    /**
+     * Attach event handler to the submit action of the create table minimal form
+     * and retrieve the full table form and display it in a dialog
+     * 
+     * @uses    PMA_ajaxShowMessage()
+     */
     $("#create_table_form_minimal").live('submit', function(event) {
         event.preventDefault();
 
         /* @todo Validate this form! */
 
+        /**
+         *  @var    button_options  Object that stores the options passed to jQueryUI
+         *                          dialog
+         */
         var button_options = {};
         button_options[PMA_messages['strCancel']] = function() {$(this).dialog('close').remove();}
 
@@ -1906,9 +1940,19 @@ $(document).ready(function() {
         
     });
 
+    /**
+     * Attach event handler for submission of create table form
+     * 
+     * @uses    PMA_ajaxShowMessage()
+     * @uses    $.PMA_sort_table()
+     * @uses    window.parent.refreshNavigation()
+     */
     $("#create_table_form").find("input[name=submit_num_fields], input[name=do_save_data]").live('click', function(event) {
         event.preventDefault();
 
+        /**
+         *  @var    the_form    object referring to the create table form
+         */
         var the_form = $("#create_table_form");
 
         PMA_ajaxShowMessage(PMA_messages['strProcessingRequest']);
@@ -1918,7 +1962,6 @@ $(document).ready(function() {
             //User wants to add more fields to the table
             $.post($(the_form).attr('action'), $(the_form).serialize() + "&submit_num_fields=" + $(this).val(), function(data) {
                 $("#create_table_dialog").html(data);
-                
             }) //end $.post()
         }
         else if($(this).attr('name') == 'do_save_data') {
@@ -1928,12 +1971,30 @@ $(document).ready(function() {
                     PMA_ajaxShowMessage(data.message);
                     $("#create_table_dialog").dialog("close").remove();
 
+                    /**
+                     * @var tables_table    Object referring to the <tbody> element that holds the list of tables
+                     */
                     var tables_table = $("#tablesForm").find("tbody").not("#tbl_summary_row");
 
+                    /**
+                     * @var curr_last_row   Object referring to the last <tr> element in {@link tables_table}
+                     */
                     var curr_last_row = $(tables_table).find('tr:last');
+                    /**
+                     * @var curr_last_row_index_string   String containing the index of {@link curr_last_row}
+                     */
                     var curr_last_row_index_string = $(curr_last_row).find('input:checkbox').attr('id').match(/\d+/)[0];
+                    /**
+                     * @var curr_last_row_index Index of {@link curr_last_row}
+                     */
                     var curr_last_row_index = parseFloat(curr_last_row_index_string);
+                    /**
+                     * @var new_last_row_index   Index of the new row to be appended to {@link tables_table}
+                     */
                     var new_last_row_index = curr_last_row_index + 1;
+                    /**
+                     * @var new_last_row_id String containing the id of the row to be appended to {@link tables_table}
+                     */
                     var new_last_row_id = 'checkbox_tbl_' + new_last_row_index;
 
                     //append to table
@@ -1943,33 +2004,39 @@ $(document).ready(function() {
                     .end()
                     .appendTo(tables_table);
 
+                    //Sort the table
                     $(tables_table).PMA_sort_table('th');
 
-                    //sort the table
+                    //Refresh navigation frame as a new table has been added
-                    //PMA_sort_table(tables_table, 'th');
-
-                    //Refresh navigation frame
                     window.parent.refreshNavigation();
                 }
                 else {
                     PMA_ajaxShowMessage(data.error);
                 }
             }) // end $.post()
-        }
+        } // end elseif()
     }) // end create table form submit button actions
 
 }, 'top.frame_content'); //end $(document).ready for 'Create Table'
 
 /**
- * jQuery coding for Empty Table and Drop Table.  Used wherever libraries/
+ * Attach event handlers for Empty Table and Drop Table.  Used wherever libraries/
  * tbl_links.inc.php is used.
  */
 $(document).ready(function() {
 
-    //Empty Table
+    /**
+     * Attach Ajax event handlers for Empty Table
+     * 
+     * @uses    PMA_ajaxShowMessage()
+     * @uses    $.PMA_confirm()
+     */
     $("#empty_table_anchor").live('click', function(event) {
         event.preventDefault();
 
+        /**
+         * @var question    String containing the question to be asked for confirmation
+         */
         var question = 'TRUNCATE TABLE ' + window.parent.table;
 
         $(this).PMA_confirm(question, $(this).attr('href'), function(url) {
@@ -1988,13 +2055,22 @@ $(document).ready(function() {
                     PMA_ajaxShowMessage(data.error);
                 }
             }) // end $.get
-        })
+        }) // end $.PMA_confirm()
     }) // end Empty Table
 
-    //Drop Table
+    /**
+     * Attach Ajax event handler for Drop Table
+     * 
+     * @uses    PMA_ajaxShowMessage()
+     * @uses    $.PMA_confirm()
+     * @uses    window.parent.refreshNavigation()
+     */
     $("#drop_table_anchor").live('click', function(event) {
         event.preventDefault();
 
+        /**
+         * @var question    String containing the question to be asked for confirmation
+         */
         var question = 'DROP TABLE/VIEW ' + window.parent.table;
         $(this).PMA_confirm(question, $(this).attr('href'), function(url) {
 
@@ -2014,19 +2090,25 @@ $(document).ready(function() {
                     PMA_ajaxShowMessage(data.error);
                 }
             }) // end $.get
-        })
+        }) // end $.PMA_confirm()
-    })
+    }) // end $().live()
 }, 'top.frame_content'); //end $(document).ready() for libraries/tbl_links.inc.php
 
 /**
- * jQuery coding for Drop Trigger.  Used on tbl_structure.php
+ * Attach Ajax event handlers for Drop Trigger.  Used on tbl_structure.php
  */
 $(document).ready(function() {
 
     $(".drop_trigger_anchor").live('click', function(event) {
         event.preventDefault();
 
+        /**
+         * @var curr_row    Object reference to the current trigger's <tr>
+         */
         var curr_row = $(this).parents('tr');
+        /**
+         * @var question    String containing the question to be asked for confirmation
+         */
         var question = 'DROP TRIGGER IF EXISTS `' + $(curr_row).children('td:first').text() + '`';
 
         $(this).PMA_confirm(question, $(this).attr('href'), function(url) {
@@ -2045,22 +2127,28 @@ $(document).ready(function() {
                 else {
                     PMA_ajaxShowMessage(data.error);
                 }
-            }) // end $.get
+            }) // end $.get()
-        })
+        }) // end $.PMA_confirm()
-    })
+    }) // end $().live()
 }, 'top.frame_content'); //end $(document).ready() for Drop Trigger
 
 /**
- * jQuery coding for Drop Database. Moved here from db_structure.js as it was
+ * Attach Ajax event handlers for Drop Database. Moved here from db_structure.js 
- * also required on db_create.php
+ * as it was also required on db_create.php
- *
+ * 
+ * @uses    $.PMA_confirm()
+ * @uses    PMA_ajaxShowMessage()
+ * @uses    window.parent.refreshNavigation()
+ * @uses    window.parent.refreshMain()
  */
 $(document).ready(function() {
-    //Drop Database
     $("#drop_db_anchor").live('click', function(event) {
         event.preventDefault();
 
         //context is top.frame_content, so we need to use window.parent.db to access the db var
+        /**
+         * @var question    String containing the question to be asked for confirmation
+         */
         var question = PMA_messages['strDropDatabaseStrongWarning'] + '\n' + PMA_messages['strDoYouReally'] + ' :\n' + 'DROP DATABASE ' + window.parent.db;
 
         $(this).PMA_confirm(question, $(this).attr('href') ,function(url) {
@@ -2070,14 +2158,16 @@ $(document).ready(function() {
                 //Database deleted successfully, refresh both the frames
                 window.parent.refreshNavigation();
                 window.parent.refreshMain();
-            })
+            }) // end $.get()
-        });
+        }); // end $.PMA_confirm()
     }); //end of Drop Database Ajax action
-})
+}) // end of $(document).ready() for Drop Database
 
 /**
- * jQuery coding for 'Create Database'.  Used wherever libraries/
+ * Attach Ajax event handlers for 'Create Database'.  Used wherever libraries/
  * display_create_database.lib.php is used, ie main.php and server_databases.php
+ *
+ * @uses    PMA_ajaxShowMessage()
  */
 $(document).ready(function() {
 
@@ -2103,18 +2193,24 @@ $(document).ready(function() {
             else {
                 PMA_ajaxShowMessage(data.error);
             }
-        })
+        }) // end $.post()
-    })
+    }) // end $().live()
-})
+})  // end $(document).ready() for Create Database
 
 /**
- * jQuery coding for 'Change Password' on main.php
+ * Attach Ajax event handlers for 'Change Password' on main.php
  */
 $(document).ready(function() {
 
+    /**
+     * Attach Ajax event handler on the change password anchor
+     */
     $('#change_password_anchor').live('click', function(event) {
         event.preventDefault();
 
+        /**
+         * @var button_options  Object containing options to be passed to jQueryUI's dialog
+         */
         var button_options = {};
 
         button_options[PMA_messages['strCancel']] = function() {$(this).dialog('close').remove();}
@@ -2127,12 +2223,20 @@ $(document).ready(function() {
                 buttons : button_options
             })
             .append(data);
-        })
+        }) // end $.get()
-    })
+    }) // end handler for change password anchor
 
+    /**
+     * Attach Ajax event handler for Change Password form submission
+     * 
+     * @uses    PMA_ajaxShowMessage()
+     */
     $("#change_password_form").find('input[name=change_pw]').live('click', function(event) {
         event.preventDefault();
 
+        /**
+         * @var the_form    Object referring to the change password form
+         */
         var the_form = $("#change_password_form");
 
         PMA_ajaxShowMessage(PMA_messages['strProcessingRequest']);
@@ -2150,6 +2254,6 @@ $(document).ready(function() {
             else {
                 PMA_ajaxShowMessage(data.error);
             }
-        })
+        }) // end $.post()
-    })
+    }) // end handler for Change Password form submission
-})
+}) // end $(document).ready() for Change Password

js/sql.js

@@ -40,7 +40,7 @@ function getFieldName(this_field_obj, disp_mode) {
  * The function that iterates over each row in the table_results and appends a
  * new inline edit anchor to each table row.
  *
- * @param   string  disp_mode
+ * @param   disp_mode   string
  */
 function appendInlineAnchor(disp_mode) {
     if(disp_mode == 'vertical') {
@@ -78,18 +78,33 @@ function appendInlineAnchor(disp_mode) {
     }
 }
 
+/**#@+
+ * @memberOf    jQuery
+ * @namespace   jQuery
+ */
+
 /**
- * Ajax scripts for sql and browse pages
+ * @description <p>Ajax scripts for sql and browse pages</p>
  *
  * Actions ajaxified here:
- * Retrieve results of an SQL query
+ * <ul>
- * Paginate the results table
+ * <li>Retrieve results of an SQL query</li>
- * Sort the results table
+ * <li>Paginate the results table</li>
- * Change table according to display options
+ * <li>Sort the results table</li>
- * Inline editing of data
+ * <li>Change table according to display options</li>
+ * <li>Inline editing of data</li>
+ * </ul>
+ *
+ * @name        document.ready
+ * @function
+ * @augments    jQuery.fn
  */
 $(document).ready(function() {
 
+    /**
+     * @lends   jQuery
+     */
+
     /**
      * @var disp_mode   current value of the direction in which the table is displayed
      */
@@ -102,6 +117,8 @@ $(document).ready(function() {
     /**
      * Attach the {@link appendInlineAnchor} function to a custom event, which
      * will be triggered manually everytime the table of results is reloaded
+     * @function
+     * @name    sqlqueryresults_live
      */
     $("#sqlqueryresults").live('appendAnchor',function() {
         appendInlineAnchor(disp_mode);
@@ -123,7 +140,8 @@ $(document).ready(function() {
     /**
      * Ajax Event handler for 'SQL Query Submit'
      *
-     * @uses    PMA_ajaxShowMessage()
+     * @see    PMA_ajaxShowMessage()
+     * @inner
      */
     $("#sqlqueryform").live('submit', function(event) {
         event.preventDefault();
@@ -220,8 +238,8 @@ $(document).ready(function() {
     /**
      * Ajax Event handlers for Inline Editing
      *
-     * @uses    PMA_ajaxShowMessage()
+     * @see    PMA_ajaxShowMessage()
-     * @uses    getFieldName()
+     * @see    getFieldName()
      */
 
     /**
@@ -566,3 +584,5 @@ $(document).ready(function() {
         }) // end $.post()
     }) // End After editing, clicking again should post data
 }, 'top.frame_content') // end $(document).ready()
+
+/**#@- */

js/tbl_change.js

@@ -1,6 +1,10 @@
 /* vim: set expandtab sw=4 ts=4 sts=4: */
 /**
- * function used in table data manipulation pages
+ * @fileoverview    function used in table data manipulation pages
+ *
+ * @requires    jQuery
+ * @requires    jQueryUI
+ * @requires    js/functions.js
  *
  * @version $Id$
  */
@@ -249,13 +253,24 @@ function unNullify(urlField, multi_edit)
 } // end of the 'unNullify()' function
 
 /**
- * Ajax handlers for this page
+ * Ajax handlers for Change Table page
+ *
+ * Actions Ajaxified here:
+ * Submit Data to be inserted into the table
+ * Restart insertion with 'N' rows.
  */
 $(document).ready(function() {
 
-    //Submission of data to be inserted into table
+    /**
+     * Submission of data to be inserted into table
+     * 
+     * @uses    PMA_ajaxShowMessage()
+     */
     $("#insertForm").live('submit', function(event) {
 
+        /**
+         * @var the_form    Object referring to the insertion form
+         */
         var the_form = $(this);
         event.preventDefault();
 
@@ -265,6 +280,7 @@ $(document).ready(function() {
         $.post($(the_form).attr('action'), $(the_form).serialize(), function(data) {
             if(data.success == true) {
                 PMA_ajaxShowMessage(data.message);
+
                 $("#topmenucontainer")
                 .next('div')
                 .remove()
@@ -277,6 +293,7 @@ $(document).ready(function() {
                     $(notice_class).remove();
                 }
 
+                //Clear the data in the forms
                 $(the_form).find('input:reset').trigger('click');
             }
             else {
@@ -285,15 +302,27 @@ $(document).ready(function() {
         })
     }) // end submission of data to be inserted into table
 
-    //Restart Insertion form
+    /**
+     * Restart Insertion form
+     */
     $("#insert_rows").live('change', function(event) {
         event.preventDefault();
 
+        /**
+         * @var curr_rows   Number of current insert rows already on page
+         */
         var curr_rows = $(".insertRowTable").length;
+        /**
+         * @var target_rows Number of rows the user wants
+         */
         var target_rows = $("#insert_rows").val();
 
         if(curr_rows < target_rows ) {
             while( curr_rows < target_rows ) {
+
+                /**
+                 * @var last_row    Object referring to the last row
+                 */
                 var last_row = $("#insertForm").find(".insertRowTable:last");
 
                 //Clone the insert tables
@@ -308,17 +337,20 @@ $(document).ready(function() {
                      * name is of format funcs[multi_edit][10][<long random string of alphanum chars>]
                      */
 
+                    /**
+                     * @var this_name   String containing name of the input/select elements
+                     */
                     var this_name = $(this).attr('name');
-                    //split at [10], so we have the parts that can be concatenated later
+                    /** split {@link this_name} at [10], so we have the parts that can be concatenated later */
                     var name_parts = this_name.split(/\[\d+\]/);
-                    //extract the [10]
+                    /** extract the [10] from  {@link name_parts} */
                     var old_row_index_string = this_name.match(/\[\d+\]/)[0];
-                    //extract 10 - had to split into two steps to accomodate double digits
+                    /** extract 10 - had to split into two steps to accomodate double digits */
                     var old_row_index = parseInt(old_row_index_string.match(/\d+/)[0]);
 
-                    //calculate next index i.e. 11
+                    /** calculate next index i.e. 11 */
                     var new_row_index = old_row_index + 1;
-                    //generate the new name i.e. funcs[multi_edit][11][foobarbaz]
+                    /** generate the new name i.e. funcs[multi_edit][11][foobarbaz] */
                     var new_name = name_parts[0] + '[' + new_row_index + ']' + name_parts[1];
 
                     $(this).attr('name', new_name);
@@ -331,10 +363,17 @@ $(document).ready(function() {
                     .after('<label for="insert_ignore_check_1">' + PMA_messages['strIgnore'] + '</label>');
                 }
                 else {
+
+                    /**
+                     * @var last_checkbox   Object reference to the last checkbox in #insertForm
+                     */
                     var last_checkbox = $("#insertForm").children('input:checkbox:last');
 
+                    /** name of {@link last_checkbox} */
                     var last_checkbox_name = $(last_checkbox).attr('name');
+                    /** index of {@link last_checkbox} */
                     var last_checkbox_index = parseInt(last_checkbox_name.match(/\d+/));
+                    /** name of new {@link last_checkbox} */
                     var new_name = last_checkbox_name.replace(/\d+/,last_checkbox_index+1);
 
                     $(last_checkbox)
@@ -359,4 +398,4 @@ $(document).ready(function() {
             }
         }
     })
-}, 'top.frame_content'); //end Ajax handlers
+}, 'top.frame_content'); //end $(document).ready()

js/tbl_select.js

@@ -1,8 +1,23 @@
 /**
- * JavaScript functions used on tbl_select.php
+ * @fileoverview JavaScript functions used on tbl_select.php
+ *
+ * @requires    jQuery
+ * @requires    js/functions.js
+ */
+
+/**
+ * Ajax event handlers for this page
+ *
+ * Actions ajaxified here:
+ * Table Search
  */
 $(document).ready(function() {
 
+    /**
+     * Ajax event handler for Table Search
+     * 
+     * @uses    PMA_ajaxShowMessage()
+     */
     $("#tbl_search_form").live('submit', function(event) {
         event.preventDefault();
 
@@ -14,4 +29,4 @@ $(document).ready(function() {
             $("#searchresults").html(data);
         })
     })
-}, 'top.frame_content');
+}, 'top.frame_content'); // end $(document).ready()