Added documentation to PHP files

libraries/common.lib.php

@@ -661,6 +661,9 @@ function PMA_mysqlDie($error_message = '', $the_query = '',
             $error_msg_output .= '</fieldset>' . "\n\n";
        }
 
+        /**
+         * If in an Ajax request, don't just echo and exit.  Use PMA_ajaxResponse()
+         */
         if($GLOBALS['is_ajax_request'] == true) {
             PMA_ajaxResponse($error_msg_output, false);
         }
@@ -1009,6 +1012,12 @@ if (!$jsonly)
  */
 function PMA_showMessage($message, $sql_query = null, $type = 'notice', $is_view = false)
 {
+    /*
+     * PMA_ajaxResponse uses this function to collect the string of HTML generated
+     * for showing the message.  Use output buffering to collect it and return it
+     * in a string.  In some special cases on sql.php, buffering has to be disabled
+     * and hence we check with $GLOBALS['buffer_message']
+     */
     if( $GLOBALS['is_ajax_request'] == true && !isset($GLOBALS['buffer_message']) ) {
         ob_start();
     }
@@ -1050,6 +1059,8 @@ function PMA_showMessage($message, $sql_query = null, $type = 'notice', $is_view
     }
     unset($tbl_status);
 
+    // In an Ajax request, $GLOBALS['cell_align_left'] may not be defined. Hence,
+    // check for it's presence before using it
     echo '<div align="' . ( isset($GLOBALS['cell_align_left']) ? $GLOBALS['cell_align_left'] : '' ) . '">' . "\n";
 
     if ($message instanceof PMA_Message) {
@@ -1286,6 +1297,7 @@ function PMA_showMessage($message, $sql_query = null, $type = 'notice', $is_view
         }
 
         // see in js/functions.js the jQuery code attached to id inline_edit
+        // document.write conflicts with jQuery, hence used $().append()
         $inline_edit = "<script type=\"text/javascript\">\n" .
             "//<![CDATA[\n" .
             "$('.tools').append('[<a href=\"#\" title=\"" .
@@ -1300,6 +1312,9 @@ function PMA_showMessage($message, $sql_query = null, $type = 'notice', $is_view
     }
     echo '</div><br />' . "\n";
 
+    // If we are in an Ajax request, we have most probably been called in 
+    // PMA_ajaxResponse().  Hence, collect the buffer contents and return it 
+    // to PMA_ajaxResponse(), which will encode it for JSON.
     if( $GLOBALS['is_ajax_request'] == true && !isset($GLOBALS['buffer_message']) ) {
         $buffer_contents =  ob_get_contents();
         ob_end_clean();
@@ -2560,6 +2575,7 @@ function PMA_generate_slider_effect($id, $message)
      * opening the <div> with PHP itself instead of JavaScript.
      *
      * @todo find a better solution that uses $.append(), the recommended method
+     * maybe by using an additional param, the id of the div to append to
      */
     ?>
 <div id="<?php echo $id; ?>" <?php echo $GLOBALS['cfg']['InitialSlidersState'] == 'closed' ? ' style="display: none; overflow:auto;"' : ''; ?>>
@@ -2966,10 +2982,12 @@ function PMA_ajaxResponse($message, $success = true, $extra_data = array())
         }
     }
 
+    // If extra_data has been provided, append it to the response array
     if( count($extra_data) > 0 ) {
         $response = array_merge($response, $extra_data);
     }
 
+    // Set the Content-Type header to JSON so that jQuery parses the response correctly
     if(!isset($GLOBALS['is_header_sent'])) {
         header("Content-Type: application/json");
     }

libraries/db_info.inc.php

@@ -269,6 +269,7 @@ unset($each_table, $tbl_group_sql, $db_info_result);
 
 /**
  * Displays top menu links
+ * If in an Ajax request, we do not need to show this
  */
 if($GLOBALS['is_ajax_request'] != true) {
     require './libraries/db_links.inc.php';

libraries/display_tbl.lib.php

@@ -1031,6 +1031,7 @@ function PMA_displayTableBody(&$dt_result, &$is_display, $map, $analyzed_sql) {
     $vertical_display['delete']     = array();
     $vertical_display['data']       = array();
     $vertical_display['row_delete'] = array();
+    // name of the class added to all inline editable elements
     $data_inline_edit_class = 'data_inline_edit';
 
     // Correction University of Virginia 19991216 in the while below
@@ -1118,6 +1119,7 @@ function PMA_displayTableBody(&$dt_result, &$is_display, $map, $analyzed_sql) {
 
                 $edit_str = PMA_getIcon('b_edit.png', __('Edit'), true);
 
+                // Class definitions required for inline editing jQuery scripts
                 $edit_anchor_class = "edit_row_anchor";
                 if( $clause_is_unique == 0) {
                     $edit_anchor_class .= ' nonunique';
@@ -2322,10 +2324,12 @@ function PMA_handle_non_printable_contents($category, $content, $transform_funct
  * @param   string  $default_function
  * @param   string  $nowrap
  * @param   string  $where_comparison
+ * @param   bool    $is_field_truncated
  * @return  string  formatted data
  */
 function PMA_prepare_row_data($mouse_events, $class, $condition_field, $analyzed_sql, $meta, $map, $data, $transform_function, $default_function, $nowrap, $where_comparison, $transform_options, $is_field_truncated ) {
 
+    // Define classes to be added to this data field based on the type of data
     $enum_class = '';
     if(strpos($meta->flags, 'enum') !== false) {
         $enum_class = ' enum';

libraries/display_tbl_links.lib.php

@@ -56,6 +56,10 @@ if ($doWriteModifyAt == 'left') {
            . '    </td>' . "\n";
     }
 }
+/*
+ * Where clause for selecting this row uniquely is provided as a hidden input.
+ * Used by jQuery scripts for handling inline editing
+ */
 if( !empty($where_clause)) {
     echo '<input type="hidden" class="where_clause" value ="' . $where_clause . '" />';
 }

libraries/server_links.inc.php

@@ -16,6 +16,7 @@ require_once './libraries/server_common.inc.php';
 
 PMA_checkParameters(array('is_superuser', 'url_query'), TRUE, FALSE);
 
+// Don't print all these links if in an Ajax request
 if (!$GLOBALS['is_ajax_request']) {
     /**
      * Counts amount of navigation tabs

server_privileges.php

@@ -976,6 +976,9 @@ if (isset($_REQUEST['adduser_submit']) || isset($_REQUEST['change_copy'])) {
                     }
 
 
+                    /**
+                     * If we are not in an Ajax request, we can't reload navigation now
+                     */
                     if($GLOBALS['is_ajax_request'] != true) {
                         // this is needed in case tracking is on:
                         $GLOBALS['db'] = $username;
@@ -1380,7 +1383,9 @@ if( $GLOBALS['is_ajax_request'] && !isset($_REQUEST['export']) && !isset($_REQUE
     }
 
     if(isset($_REQUEST['adduser_submit']) || isset($_REQUEST['change_copy'])) {
-        //generate html on the fly for the new user that was just created.
+        /**
+         * generate html on the fly for the new user that was just created.
+         */
         $new_user_string = '<tr>'."\n"
                            .'<td> <input type="checkbox" name="selected_usr[]" id="checkbox_sel_users_" value="' . htmlspecialchars($username) . '&amp;#27;' . htmlspecialchars($hostname) . '" /> </td>'."\n"
                            .'<td><label for="checkbox_sel_users_">' . (empty($username) ? '<span style="color: #FF0000">' . __('Any') . '</span>' : htmlspecialchars($username) ) . '</label></td>' . "\n"
@@ -1414,7 +1419,10 @@ if( $GLOBALS['is_ajax_request'] && !isset($_REQUEST['export']) && !isset($_REQUE
 
         $extra_data['new_user_string'] = $new_user_string;
 
-        //Generate the string for this alphabet's initial
+        /**
+         * Generate the string for this alphabet's initial, to update the user
+         * pagination
+         */
         $new_user_initial = strtoupper(substr($username, 0, 1));
         $new_user_initial_string = '<a href="server_privileges.php?' . $GLOBALS['url_query'] . '&initial=' . $new_user_initial
             .'>' . $new_user_initial . '</a>';
@@ -1553,6 +1561,7 @@ if (empty($_REQUEST['adduser']) && (! isset($checkprivs) || ! strlen($checkprivs
 
             /**
              * Displays the initials
+             * In an Ajax request, we don't need to show this
              */
 
             if( $GLOBALS['is_ajax_request'] != true ) {

sql.php

@@ -51,6 +51,8 @@ if (isset($fields['dbase'])) {
 /**
  * During inline edit, if we have a relational field, show the dropdown for it
  *
+ * Logic taken from libraries/display_tbl_lib.php
+ *
  * This doesn't seem to be the right place to do this, but I can't think of any
  * better place either.
  */
@@ -86,6 +88,8 @@ if(isset($_REQUEST['get_relational_values']) && $_REQUEST['get_relational_values
 
 /**
  * Just like above, find possible values for enum fields during inline edit.
+ *
+ * Logic taken from libraries/display_tbl_lib.php
  */
 if(isset($_REQUEST['get_enum_values']) && $_REQUEST['get_enum_values'] == true) {
     $field_info_query = 'SHOW FIELDS FROM `' . $db . '`.`' . $table . '` LIKE \'' . $_REQUEST['column'] . '\' ;';
@@ -600,9 +604,16 @@ if (0 == $num_rows || $is_affected) {
     
     if( $GLOBALS['is_ajax_request'] == true) {
 
+        /**
+         * If we are in inline editing, we need to process the relational and
+         * transformed fields, if they were edited. After that, output the correct
+         * link/transformed value and exit
+         *
+         * Logic taken from libraries/display_tbl.lib.php
+         */
+
         if(isset($_REQUEST['rel_fields_list']) && $_REQUEST['rel_fields_list'] != '') {
             //handle relations work here for updated row.
-            // @todo : $where_comparison
             require_once './libraries/relation.lib.php';
 
             $map = PMA_getForeigners($db, $table, '', 'both');

tbl_create.php

@@ -243,7 +243,12 @@ if (isset($_REQUEST['do_save_data'])) {
 
         if($GLOBALS['is_ajax_request'] == true) {
 
-            //construct the html for the newly created table's row to be appended
+            /**
+             * construct the html for the newly created table's row to be appended
+             * to the list of tables.
+             *
+             * Logic taken from db_structure.php
+             */
 
             $tbl_url_params = array();
             $tbl_url_params['db'] = $db;

themes/original/css/theme_right.css.php

@@ -1272,17 +1272,17 @@ table#serverconnection_trg_local  {
   *  Ajax notification styling
   */
  .ajax_notification {
-    top: 0px;
+    top: 0px;           /** The notification needs to be shown on the top of the page */
     position: fixed;
     margin-top: 0;
     margin-right: auto;
     margin-bottom: 0;
     margin-left: auto;
-    padding: 3px 5px;
+    padding: 3px 5px;   /** Keep a little space on the sides of the text */
     min-width: 70px;
-    max-width: 350px;
+    max-width: 350px;   /** This value might have to be changed */
     background-color: #FFD700;
-    z-index: 1100;
+    z-index: 1100;      /** If this is not kept at a high z-index, the jQueryUI modal dialogs (z-index:1000) might hide this */
     text-align: center;
     display: block;
     left: 0;
@@ -1293,6 +1293,7 @@ table#serverconnection_trg_local  {
  }
 
  #loading_parent {
+    /** Need this parent to properly center the notification division */
     position: relative;
     width: 100%;
  }

user_password.php

@@ -72,6 +72,9 @@ if (isset($_REQUEST['nopass'])) {
     }
 
     if($GLOBALS['is_ajax_request'] == true && $_error == true) {
+        /**
+         * If in an Ajax request, we don't need to show the rest of the page
+         */
         PMA_ajaxResponse($message, false);
     }