- Patch #670250 by boombatower: more documentation clean-ups.

5 files changed, 43 insertions, 28 deletions

diff --git a/includes/ajax.inc b/includes/ajax.inc
index 8a2c4b07b..c7c32ce92 100644
--- a/includes/ajax.inc
+++ b/includes/ajax.inc
@@ -328,7 +328,7 @@ function ajax_deliver($page_callback_result) {
   }
   elseif (is_array($page_callback_result) && isset($page_callback_result['#type']) && ($page_callback_result['#type'] == 'ajax_commands')) {
     // Complex AJAX callbacks can return a result that contains a specific
-    // set of commands to send to the browser.
+    // set of commands to send to the browser. 
     if (isset($page_callback_result['#ajax_commands'])) {
       $commands = $page_callback_result['#ajax_commands'];
     }
diff --git a/includes/authorize.inc b/includes/authorize.inc
index 28d475add..772481b2d 100644
--- a/includes/authorize.inc
+++ b/includes/authorize.inc
@@ -19,7 +19,7 @@ function authorize_filetransfer_form($form_state) {
   // CSS we depend on lives in modules/system/maintenance.css, which is loaded
   // via the default maintenance theme.
   $form['#attached']['js'][] = $base_url . '/misc/authorize.js';
-
+  
   // Get all the available ways to transfer files.
   if (empty($_SESSION['authorize_filetransfer_backends'])) {
     drupal_set_message(t('Unable to continue, no available methods of file transfer'), 'error');
@@ -182,7 +182,7 @@ function authorize_filetransfer_form_submit($form, &$form_state) {
         variable_set('authorize_filetransfer_connection_settings_' . $filetransfer_backend, $connection_settings);
 
         $filetransfer = authorize_get_filetransfer($filetransfer_backend, $form_state['values']['connection_settings'][$filetransfer_backend]);
-
+        
         // Now run the operation.
         authorize_run_operation($filetransfer);
       }
diff --git a/includes/update.inc b/includes/update.inc
index b7a45d2c5..18dd7a8df 100644
--- a/includes/update.inc
+++ b/includes/update.inc
@@ -10,8 +10,7 @@
  */
 
 /**
- * Disable anything in the {system} table that is not compatible with the
- * current version of Drupal core.
+ * Disable any items in the {system} table that are not core capatible.
  */
 function update_fix_compatibility() {
   $incompatible = array();
@@ -58,6 +57,8 @@ function update_check_incompatibility($name, $type = 'module') {
 }
 
 /**
+ * Performs extra steps required to bootstrap when using a Drupal 6 database.
+ *
  * Users who still have a Drupal 6 database (and are in the process of
  * updating to Drupal 7) need extra help before a full bootstrap can be
  * achieved. This function does the necessary preliminary work that allows
@@ -166,8 +167,8 @@ function update_prepare_d7_bootstrap() {
 function update_fix_d7_requirements() {
   global $conf;
 
-  // Rewrite the settings.php file if necessary.
-  // @see update_prepare_d7_bootstrap().
+  // Rewrite the settings.php file if necessary, see
+  // update_prepare_d7_bootstrap().
   global $update_rewrite_settings, $db_url;
   if (!empty($update_rewrite_settings)) {
     $databases = update_parse_db_url($db_url);
@@ -343,8 +344,8 @@ function update_fix_d7_requirements() {
     }
 
     // Rename 'site_offline_message' variable to 'maintenance_mode_message'.
-    // Old variable is removed in update for system.module.
-    // @see system_update_7036().
+    // Old variable is removed in update for system.module, see
+    // system_update_7036().
     if ($message = variable_get('site_offline_message', NULL)) {
       variable_set('maintenance_mode_message', $message);
     }
@@ -358,8 +359,8 @@ function update_fix_d7_requirements() {
 /**
  * Register the currently installed profile in the system table.
  *
- * Install profiles are now treated as modules by Drupal, and have an upgrade path
- * based on their schema version in the system table.
+ * Install profiles are now treated as modules by Drupal, and have an upgrade
+ * path based on their schema version in the system table.
  *
  * The install profile will be set to schema_version 0, as it has already been
  * installed. Any other hook_update_N functions provided by the install profile
@@ -423,8 +424,10 @@ function update_fix_d7_install_profile() {
 }
 
 /**
- * Parse database connection URLs (in the old, pre-Drupal 7 format) and
- * return them as an array of database connection information.
+ * Parase pre-Drupal 7 database connection URLs and return D7 compatible array.
+ *
+ * @return
+ *   Drupal 7 DBTNG compatible array of database connection information.
  */
 function update_parse_db_url($db_url) {
   $databases = array();
@@ -448,8 +451,7 @@ function update_parse_db_url($db_url) {
 }
 
 /**
- * Perform one update and store the results which will later be displayed on
- * the finished page.
+ * Perform one update and store the results for display on finished page.
  *
  * If an update function completes successfully, it should return a message
  * as a string indicating success, for example:
diff --git a/includes/xmlrpc.inc b/includes/xmlrpc.inc
index 688605bf2..161abd83f 100644
--- a/includes/xmlrpc.inc
+++ b/includes/xmlrpc.inc
@@ -3,7 +3,9 @@
 
 /**
  * @file
- * Drupal XML-RPC library. Based on the IXR - The Incutio XML-RPC Library - (c) Incutio Ltd 2002-2005
+ * Drupal XML-RPC library.
+ *
+ * Based on the IXR - The Incutio XML-RPC Library - (c) Incutio Ltd 2002-2005
  * Version 1.7 (beta) - Simon Willison, 23rd May 2005
  * Site:   http://scripts.incutio.com/xmlrpc/
  * Manual: http://scripts.incutio.com/xmlrpc/manual.php
@@ -11,11 +13,11 @@
  */
 
 /**
- * Recursively turn a data structure into objects with 'data' and 'type' attributes.
+ * Turn a data structure into objects with 'data' and 'type' attributes.
  *
  * @param $data
  *   The data structure.
- * @param  $type
+ * @param $type
  *   Optional type assign to $data.
  * @return
  *   Object.
@@ -48,8 +50,7 @@ function xmlrpc_value($data, $type = FALSE) {
  *   Variable whose type should be mapped.
  * @return
  *   XML-RPC type as string.
- * @see
- *   http://www.xmlrpc.com/spec#scalars
+ * @see http://www.xmlrpc.com/spec#scalars
  */
 function xmlrpc_value_calculate_type($xmlrpc_value) {
   // http://www.php.net/gettype: Never use gettype() to test for a certain type [...] Instead, use the is_* functions.
@@ -84,6 +85,7 @@ function xmlrpc_value_calculate_type($xmlrpc_value) {
  * Generate XML representing the given value.
  *
  * @param $xmlrpc_value
+ *   A value to be represented in XML.
  * @return
  *   XML representation of value.
  */
@@ -148,8 +150,10 @@ function xmlrpc_message($message) {
 }
 
 /**
- * Parse an XML-RPC message. If parsing fails, the faultCode and faultString
- * will be added to the message object.
+ * Parse an XML-RPC message.
+ *
+ * If parsing fails, the faultCode and faultString will be added to the message
+ * object.
  *
  * @param $xmlrpc_message
  *   Object generated by xmlrpc_message()
@@ -428,10 +432,11 @@ function xmlrpc_base64_get_xml($xmlrpc_base64) {
  *     http://www.example.com/xmlrpc.php
  * @param ...
  *   For one request:
- *     The method name followed by a variable number of arguments to the method.
+ *     The method name followed by a variable number of arguments to the
+ *     method.
  *   For multiple requests (system.multicall):
- *     An array of call arrays. Each call array follows the pattern of the single
- *     request: method name followed by the arguments to the method.
+ *     An array of call arrays. Each call array follows the pattern of the
+ *     single request: method name followed by the arguments to the method.
  * @return
  *   Either the return value of the method on success, or FALSE.  If FALSE is
  *   returned, see xmlrpc_errno() and xmlrpc_error_msg().
diff --git a/includes/xmlrpcs.inc b/includes/xmlrpcs.inc
index ea0858276..ba8ca00e1 100644
--- a/includes/xmlrpcs.inc
+++ b/includes/xmlrpcs.inc
@@ -2,6 +2,11 @@
 // $Id$
 
 /**
+ * @file
+ * Provides API for defining and handling XML-RPC requests.
+ */
+
+/**
  * The main entry point for XML-RPC requests.
  *
  * @param $callbacks
@@ -38,7 +43,7 @@ function xmlrpc_server($callbacks) {
   // We build an array of all method names by combining the built-ins
   // with those defined by modules implementing the _xmlrpc hook.
   // Built-in methods are overridable.
-  foreach (array_merge($defaults, (array)$callbacks) as $key => $callback) {
+  foreach (array_merge($defaults, (array) $callbacks) as $key => $callback) {
     // we could check for is_array($callback)
     if (is_int($key)) {
       $method = $callback[0];
@@ -138,6 +143,8 @@ function xmlrpc_server_get() {
  * Dispatch the request and any parameters to the appropriate handler.
  *
  * @param $xmlrpc_server
+ *   Contains information about this XML-RPC server, the methods it provides,
+ *   their signatures, etc.
  * @param $methodname
  *   The external XML-RPC method name, e.g. 'system.methodHelp'
  * @param $args
@@ -252,7 +259,8 @@ function xmlrpc_server_list_methods() {
 
 /**
  * XML-RPC method system.getCapabilities maps to this function.
- * See http://groups.yahoo.com/group/xml-rpc/message/2897
+ *
+ * @see http://groups.yahoo.com/group/xml-rpc/message/2897
  */
 function xmlrpc_server_get_capabilities() {
   return array(
@@ -280,7 +288,7 @@ function xmlrpc_server_get_capabilities() {
  *
  * @param $methodname
  *   Name of method for which we return a method signature.
- * @return array
+ * @return
  *   An array of types representing the method signature of the
  *   function that the methodname maps to. The methodSignature of
  *   this function is 'array', 'string' because it takes an array