Issue #1315886 by xjm, jhodgdon: Clean up API docs for includes directory, files starting with A-C.

1 files changed, 19 insertions, 13 deletions

diff --git a/includes/ajax.inc b/includes/ajax.inc
index cda55b424..e31a97daa 100644
--- a/includes/ajax.inc
+++ b/includes/ajax.inc
@@ -24,7 +24,8 @@
  * ajax_form_callback() and a defined #ajax['callback'] function.
  * However, you may optionally specify a different path to request or a
  * different callback function to invoke, which can return updated HTML or can
- * also return a richer set of @link ajax_commands Ajax framework commands @endlink.
+ * also return a richer set of
+ * @link ajax_commands Ajax framework commands @endlink.
  *
  * Standard form handling is as follows:
  *   - A form element has a #ajax property that includes #ajax['callback'] and
@@ -101,7 +102,7 @@
  * In the above example, the 'changethis' element is Ajax-enabled. The default
  * #ajax['event'] is 'change', so when the 'changethis' element changes,
  * an Ajax call is made. The form is submitted and reprocessed, and then the
- * callback is called.  In this case, the form has been automatically
+ * callback is called. In this case, the form has been automatically
  * built changing $form['replace_textfield']['#description'], so the callback
  * just returns that part of the form.
  *
@@ -188,11 +189,11 @@
  * be converted to a JSON object and returned to the client, which will then
  * iterate over the array and process it like a macro language.
  *
- * Each command item is an associative array which will be converted to a command
- * object on the JavaScript side. $command_item['command'] is the type of
- * command, e.g. 'alert' or 'replace', and will correspond to a method in the
- * Drupal.ajax[command] space. The command array may contain any other data
- * that the command needs to process, e.g. 'method', 'selector', 'settings', etc.
+ * Each command item is an associative array which will be converted to a
+ * command object on the JavaScript side. $command_item['command'] is the type
+ * of command, e.g. 'alert' or 'replace', and will correspond to a method in the
+ * Drupal.ajax[command] space. The command array may contain any other data that
+ * the command needs to process, e.g. 'method', 'selector', 'settings', etc.
  *
  * Commands are usually created with a couple of helper functions, so they
  * look like this:
@@ -222,7 +223,7 @@
  */
 
 /**
- * Render a commands array into JSON.
+ * Renders a commands array into JSON.
  *
  * @param $commands
  *   A list of macro commands generated by the use of ajax_command_*()
@@ -301,7 +302,7 @@ function ajax_render($commands = array()) {
 }
 
 /**
- * Get a form submitted via #ajax during an Ajax callback.
+ * Gets a form submitted via #ajax during an Ajax callback.
  *
  * This will load a form from the form cache used during Ajax operations. It
  * pulls the form info from $_POST.
@@ -361,6 +362,8 @@ function ajax_get_form() {
  * #ajax['path']. If processing is required that cannot be accomplished with
  * a callback, re-implement this function and set #ajax['path'] to the
  * enhanced function.
+ *
+ * @see system_menu()
  */
 function ajax_form_callback() {
   list($form, $form_state) = ajax_get_form();
@@ -396,6 +399,9 @@ function ajax_form_callback() {
  * of the page. Therefore, system_menu() sets the 'theme callback' for
  * 'system/ajax' to this function, and it is recommended that modules
  * implementing other generic Ajax paths do the same.
+ *
+ * @see system_menu()
+ * @see file_menu()
  */
 function ajax_base_page_theme() {
   if (!empty($_POST['ajax_page_state']['theme']) && !empty($_POST['ajax_page_state']['theme_token'])) {
@@ -414,7 +420,7 @@ function ajax_base_page_theme() {
 }
 
 /**
- * Package and send the result of a page callback to the browser as an Ajax response.
+ * Packages and sends the result of a page callback as an Ajax response.
  *
  * This function is the equivalent of drupal_deliver_html_page(), but for Ajax
  * requests. Like that function, it:
@@ -547,7 +553,7 @@ function ajax_prepare_response($page_callback_result) {
 }
 
 /**
- * Perform end-of-Ajax-request tasks.
+ * Performs end-of-Ajax-request tasks.
  *
  * This function is the equivalent of drupal_page_footer(), but for Ajax
  * requests.
@@ -570,7 +576,7 @@ function ajax_footer() {
 }
 
 /**
- * Form element process callback to handle #ajax.
+ * Form element processing handler for the #ajax form property.
  *
  * @param $element
  *   An associative array containing the properties of the element.
@@ -589,7 +595,7 @@ function ajax_process_form($element, &$form_state) {
 }
 
 /**
- * Add Ajax information about an element to the page to communicate with JavaScript.
+ * Adds Ajax information about an element to communicate with JavaScript.
  *
  * If #ajax['path'] is set on an element, this additional JavaScript is added
  * to the page header to attach the Ajax behaviors. See ajax.js for more