Index: includes/batch.inc
===================================================================
RCS file: /cvs/drupal/drupal/includes/batch.inc,v
retrieving revision 1.36
diff -u -r1.36 batch.inc
--- includes/batch.inc	2 Jun 2009 06:58:15 -0000	1.36
+++ includes/batch.inc	21 Jul 2009 00:15:25 -0000
@@ -17,7 +17,7 @@
  */
 
 /**
- * State-based dispatcher for the batch processing page.
+ * Dispatches batch commands for the batch processing page.
  *
  * @see _batch_shutdown()
  */
@@ -77,7 +77,7 @@
 }
 
 /**
- * Initialize the batch processing.
+ * Initializes batch processing.
  *
  * JavaScript-enabled clients are identified by the 'has_js' cookie set in
  * drupal.js. If no JavaScript-enabled page has been visited during the current
@@ -93,7 +93,7 @@
 }
 
 /**
- * Output a batch processing page with JavaScript support.
+ * Outputs a batch processing page with JavaScript support.
  *
  * This initializes the batch and error messages. Note that in JavaScript-based
  * processing, the batch processing page is displayed only once and updated via
@@ -124,7 +124,9 @@
 }
 
 /**
- * Do one pass of execution in JavaScript-mode and return progress to the browser.
+ * Does one pass of batch execution in JavaScript mode.
+ *
+ * Returns progress to the browser when the batch is done.
  *
  * @see _batch_progress_page_js()
  * @see _batch_process()
@@ -144,7 +146,7 @@
 }
 
 /**
- * Output a batch processing page without JavaScript support.
+ * Outputs a batch processing page without JavaScript support.
  *
  * @see _batch_process()
  */
@@ -196,12 +198,14 @@
 }
 
 /**
- * Process sets in a batch.
+ * Processes sets in a batch.
  *
- * If the batch was marked for progressive execution (default), this executes as
- * many operations in batch sets until an execution time of 1 second has been
- * exceeded. It will continue with the next operation of the same batch set in
- * the next request.
+ * If the batch was marked for progressive execution (default), this
+ * executes operations in batch sets until an execution time of 1
+ * second has been exceeded; otherwise, the entire set is
+ * executed. Processing will continue with the next operation of the
+ * same batch set in the next call to this function, in progressive
+ * execution mode.
  *
  * @return
  *   An array containing a completion value (in percent) and a status message.
@@ -353,7 +357,7 @@
 }
 
 /**
- * Return the batch set being currently processed.
+ * Returns the batch set currently being processed.
  */
 function &_batch_current_set() {
   $batch = &batch_get();
@@ -361,10 +365,10 @@
 }
 
 /**
- * Retrieve the next set in a batch.
+ * Prepares the next set in a batch.
  *
- * If there is a subsequent set in this batch, assign it as the new set to
- * process and execute its form submit handler (if defined), which may add
+ * If there is a subsequent set in this batch, assigns it as the new set to
+ * process and executes its form submit handler (if defined), which may add
  * further sets to this batch.
  *
  * @return
@@ -385,9 +389,9 @@
 }
 
 /**
- * End the batch processing.
+ * Ends batch processing.
  *
- * Call the 'finished' callback of each batch set to allow custom handling of
+ * Calls the 'finished' callback of each batch set to allow custom handling of
  * the results and resolve page redirection.
  */
 function _batch_finished() {
@@ -455,7 +459,7 @@
 }
 
 /**
- * Shutdown function; store the current batch data for the next request.
+ * Shutdown function: stores the current batch data for the next request.
  */
 function _batch_shutdown() {
   if ($batch = batch_get()) {
Index: includes/actions.inc
===================================================================
RCS file: /cvs/drupal/drupal/includes/actions.inc,v
retrieving revision 1.29
diff -u -r1.29 actions.inc
--- includes/actions.inc	20 Jul 2009 18:51:31 -0000	1.29
+++ includes/actions.inc	21 Jul 2009 00:15:25 -0000
@@ -7,35 +7,35 @@
  */
 
 /**
- * Perform a given list of actions by executing their callback functions.
+ * Performs a given list of actions by executing their callback functions.
  *
- * Given the IDs of actions to perform, find out what the callbacks
- * for the actions are by querying the database. Then call each callback
+ * Given the IDs of actions to perform, finds out what the callbacks
+ * for the actions are by querying the database. Then calls each callback
  * using the function call $function($object, $context, $a1, $a2)
  * where $function is the name of a function written in compliance with
  * the action specification; that is, foo($object, $context).
  *
  * @param $action_ids
- *   The ID of the action to perform. Can be a single action ID or an array
- *   of IDs. IDs of instances will be numeric; IDs of singletons will be
- *   function names.
+ *   The IDs of the actions to perform. Can be a single action ID or an array
+ *   of IDs. Numeric IDs will be looked up as action IDs in the actions
+ *   table of the database. Non-numeric IDs must match a key returned by
+ *   a hook_action_info() implementation (the key is the action function name).
  * @param $object
- *   Parameter that will be passed along to the callback. Typically the
- *   object that the action will act on; a node, user or comment object.
+ *   First parameter passed to the callback function. Typically the
+ *   object that the action will act on: a node, user, or comment object.
  * @param $context
- *   Parameter that will be passed along to the callback. $context is a
+ *   Second parameter passed to the callback function. $context is a
  *   keyed array containing extra information about what is currently
  *   happening at the time of the call. Typically $context['hook'] and
  *   $context['op'] will tell which hook-op combination resulted in this
  *   call to actions_do().
  * @param $a1
- *   Parameter that will be passed along to the callback.
+ *   Additional parameter passed to the callback function.
  * @param $a2
- *   Parameter that will be passed along to the callback.
- *
+ *   Additional parameter passed to the callback function.
  * @return
- *   An associative array containing the result of the function that
- *   performs the action, keyed on action ID.
+ *   An associative array containing the results of the callback functions,
+ *   keyed on the passed-in action ID.
  */
 function actions_do($action_ids, $object = NULL, $context = NULL, $a1 = NULL, $a2 = NULL) {
   // $stack tracks the number of recursive calls.
@@ -109,49 +109,20 @@
 }
 
 /**
- * Discover all action functions by invoking hook_action_info().
+ * Returns a list of all actions from hook_action_info() implementations.
  *
- * @code
- * mymodule_action_info() {
- *   return array(
- *     'mymodule_functiondescription_action' => array(
- *       'type' => 'node',
- *       'description' => t('Save node'),
- *       'configurable' => FALSE,
- *       'hooks' => array(
- *         'node' => array('delete', 'insert', 'update', 'view'),
- *         'comment' => array('delete', 'insert', 'update', 'view'),
- *       )
- *     )
- *   );
- * }
- * @endcode
- *
- * The description is used in presenting possible actions to the user for
- * configuration. The type is used to present these actions in a logical
- * grouping and to denote context. Some types are 'node', 'user', 'comment',
- * and 'system'. If an action is configurable it will provide form,
- * validation and submission functions. The hooks the action supports
- * are declared in the 'hooks' array.
+ * Compare with actions_get_all_actions(), which returns information on
+ * actions stored in the database. The two are synchronized by visiting
+ * /admin/structure/actions (when actions.module is enabled), which runs
+ * actions_synchronize().
  *
  * @param $reset
- *   Reset the action info static cache.
- *
+ *   Reset the action list static cache if TRUE.
  * @return
- *   An associative array keyed on function name. The value of each key is
- *   an array containing information about the action, such as type of
- *   action and description of the action, e.g.:
- *   @code
- *   $actions['node_publish_action'] = array(
- *     'type' => 'node',
- *     'description' => t('Publish post'),
- *     'configurable' => FALSE,
- *     'hooks' => array(
- *       'node' => array('presave', 'insert', 'update', 'view'),
- *       'comment' => array('delete', 'insert', 'update', 'view'),
- *     ),
- *   );
- *   @endcode
+ *   An associative array keyed on the action function name. The value
+ *   of each element is an associative array containing information about the
+ *   action, with keys 'type', 'description', 'configurable', 'hooks',
+ *   and optionally 'behavior'. See hook_action_info() for more details.
  */
 function actions_list($reset = FALSE) {
   static $actions;
@@ -165,16 +136,17 @@
 }
 
 /**
- * Retrieve all action instances from the database.
+ * Returns all action instances stored in the database.
  *
- * Compare with actions_list() which gathers actions by invoking
+ * Compare with actions_list(), which gathers actions by invoking
  * hook_action_info(). The two are synchronized by visiting
- * /admin/structure/actions (when actions.module is enabled) which runs
+ * /admin/structure/actions (when actions.module is enabled), which runs
  * actions_synchronize().
  *
  * @return
- *   Associative array keyed by action ID. Each value is an associative array
- *   with keys 'callback', 'description', 'type' and 'configurable'.
+ *   Associative array keyed by the action ID. Each
+ *   value is an associative array with keys 'callback',
+ *   'description', 'type' and 'configurable'.
  */
 function actions_get_all_actions() {
   $actions = db_query("SELECT aid, type, callback, parameters, description FROM {actions}")->fetchAllAssoc('aid', PDO::FETCH_ASSOC);
@@ -187,21 +159,22 @@
 }
 
 /**
- * Create an associative array keyed by md5 hashes of function names.
+ * Reformulates an action array so its keys are md5 hashes of function names.
  *
  * Hashes are used to prevent actual function names from going out into HTML
- * forms and coming back.
+ * forms and coming back. Use actions_function_lookup() to look up the
+ * function name, given the md5 hash.
  *
  * @param $actions
- *   An associative array with function names as keys and associative arrays
- *   with keys 'description', 'type', etc. as values. Generally the output of
- *   actions_list() or actions_get_all_actions() is given as input to this
- *   function.
- *
+ *   An associative array of actions with function names as keys, and
+ *   values that are associative arrays with keys 'description',
+ *   'type', 'configurable', and optionally 'callback'. Generally this
+ *   is the output of actions_list() or actions_get_all_actions().
  * @return
- *   An associative array keyed on md5 hash of function names. The value of
- *   each key is an associative array of function, description, and type for
- *   the action.
+ *   An associative array keyed on the md5 hashes of the function
+ *   names. The values are associative arrays with keys 'callback'
+ *   (which is either the input key or input element 'callback' to
+ *   override), 'description', 'type', and 'configurable'.
  */
 function actions_actions_map($actions) {
   $actions_map = array();
@@ -216,15 +189,15 @@
 }
 
 /**
- * Given an md5 hash of a function name, return the function name.
+ * Given an md5 hash of a function name, returns the function name.
  *
- * Faster than actions_actions_map() when you only need the function name.
+ * Does the reverse lookup of actions_actions_map(), checking for actions
+ * returned by hook_action_info() and actions stored in the database.
  *
  * @param $hash
  *   MD5 hash of a function name.
- *
  * @return
- *   The corresponding function name or FALSE if none is found.
+ *   The corresponding function name, or FALSE if none is found.
  */
 function actions_function_lookup($hash) {
   $actions_list = actions_list();
@@ -239,17 +212,18 @@
 }
 
 /**
- * Synchronize actions that are provided by modules.
+ * Synchronizes actions provided by modules with the database.
  *
- * Actions provided by modules are synchronized with actions that are stored in
- * the actions table. This is necessary so that actions that do not require
- * configuration can receive action IDs. This is not necessarily the best
- * approach, but it is the most straightforward.
+ * Actions provided by modules in hook_action_info() implementations
+ * are synchronized with actions that are stored in the actions
+ * table. This is necessary so that actions that do not require
+ * configuration can receive action IDs.
  *
  * @param $delete_orphans
- *   Boolean if TRUE, any actions that exist in the database but are no longer
- *   found in the code (for example, because the module that provides them has
- *   been disabled) will be deleted.
+ *   If TRUE, any actions that exist in the database but are no longer
+ *   returned by hook_action_info() implementations (for example,
+ *   because the module that provides them has been disabled) will be
+ *   deleted.
  */
 function actions_synchronize($delete_orphans = FALSE) {
   $actions_in_code = actions_list(TRUE);
@@ -301,22 +275,21 @@
 }
 
 /**
- * Save an action and its associated user-supplied parameter values to the database.
+ * Saves an action and its associated parameter values to the database.
  *
  * @param $function
  *   The name of the function to be called when this action is performed.
  * @param $type
- *   The type of action, to describe grouping and/or context, e.g., 'node',
+ *   The type of action, to describe grouping and/or context; e.g., 'node',
  *   'user', 'comment', or 'system'.
  * @param $params
  *   An associative array with parameter names as keys and parameter values as
  *   values.
  * @param $desc
- *   A user-supplied description of this particular action, e.g., 'Send e-mail
+ *   A human-readable description of this particular action; e.g., 'Send e-mail
  *   to Jim'.
  * @param $aid
  *   The ID of this action. If omitted, a new action is created.
- *
  * @return
  *   The ID of the action.
  */
@@ -342,11 +315,10 @@
 }
 
 /**
- * Retrieve a single action from the database.
+ * Retrieves a single action from the database.
  *
  * @param $aid
  *   The ID of the action to retrieve.
- *
  * @return
  *   The appropriate action row from the database as an object.
  */
@@ -355,7 +327,7 @@
 }
 
 /**
- * Delete a single action from the database.
+ * Deletes a single action from the database.
  *
  * @param $aid
  *   The ID of the action to delete.
Index: includes/bootstrap.inc
===================================================================
RCS file: /cvs/drupal/drupal/includes/bootstrap.inc,v
retrieving revision 1.290
diff -u -r1.290 bootstrap.inc
--- includes/bootstrap.inc	19 Jul 2009 05:26:11 -0000	1.290
+++ includes/bootstrap.inc	21 Jul 2009 00:15:25 -0000
@@ -238,9 +238,10 @@
 
 
 /**
- * Start the timer with the specified name. If you start and stop
- * the same timer multiple times, the measured intervals will be
- * accumulated.
+ * Starts the timer with the specified name.
+ * 
+ * If you start and stop the same timer multiple times, the measured
+ * intervals will be accumulated.
  *
  * @param name
  *   The name of the timer.
@@ -253,12 +254,12 @@
 }
 
 /**
- * Read the current timer value without stopping the timer.
+ * Reads the current timer value without stopping the timer.
  *
  * @param name
  *   The name of the timer.
  * @return
- *   The current timer value in ms.
+ *   The current timer value in milliseconds.
  */
 function timer_read($name) {
   global $timers;
@@ -275,14 +276,14 @@
 }
 
 /**
- * Stop the timer with the specified name.
+ * Stops the timer with the specified name.
  *
  * @param name
  *   The name of the timer.
  * @return
  *   A timer array. The array contains the number of times the
  *   timer has been started and stopped (count) and the accumulated
- *   timer value in ms (time).
+ *   timer value in milliseconds (time).
  */
 function timer_stop($name) {
   global $timers;
@@ -294,31 +295,31 @@
 }
 
 /**
- * Find the appropriate configuration directory.
+ * Finds the appropriate configuration directory.
  *
- * Try finding a matching configuration directory by stripping the website's
+ * Tries to find a matching configuration directory by stripping the website's
  * hostname from left to right and pathname from right to left. The first
- * configuration file found will be used; the remaining will ignored. If no
+ * configuration file found will be used; the remaining will be ignored. If no
  * configuration file is found, return a default value '$confdir/default'.
  *
- * Example for a fictitious site installed at
- * http://www.drupal.org:8080/mysite/test/ the 'settings.php' is searched in
- * the following directories:
- *
- *  1. $confdir/8080.www.drupal.org.mysite.test
- *  2. $confdir/www.drupal.org.mysite.test
- *  3. $confdir/drupal.org.mysite.test
- *  4. $confdir/org.mysite.test
- *
- *  5. $confdir/8080.www.drupal.org.mysite
- *  6. $confdir/www.drupal.org.mysite
- *  7. $confdir/drupal.org.mysite
- *  8. $confdir/org.mysite
- *
- *  9. $confdir/8080.www.drupal.org
- * 10. $confdir/www.drupal.org
- * 11. $confdir/drupal.org
- * 12. $confdir/org
+ * Example: for a fictitious site installed at
+ * http://www.example.com:8080/mysite/test/, the 'settings.php' file 
+ * is searched for in the following directories:
+ *
+ *  1. $confdir/8080.www.example.com.mysite.test
+ *  2. $confdir/www.example.com.mysite.test
+ *  3. $confdir/example.com.mysite.test
+ *  4. $confdir/com.mysite.test
+ *
+ *  5. $confdir/8080.www.example.com.mysite
+ *  6. $confdir/www.example.com.mysite
+ *  7. $confdir/example.com.mysite
+ *  8. $confdir/com.mysite
+ *
+ *  9. $confdir/8080.www.example.com
+ * 10. $confdir/www.example.com
+ * 11. $confdir/example.com
+ * 12. $confdir/com
  *
  * 13. $confdir/default
  *
@@ -391,7 +392,7 @@
 }
 
 /**
- * Initialize PHP environment.
+ * Initializes the PHP environment.
  */
 function drupal_environment_initialize() {
   if (!isset($_SERVER['HTTP_REFERER'])) {
@@ -441,16 +442,20 @@
 }
 
 /**
- * Validate that a hostname (for example $_SERVER['HTTP_HOST']) is safe.
+ * Validates that a hostname (for example $_SERVER['HTTP_HOST']) is safe.
  *
+ * @param $host
+ *    Host name to check.
  * @return
- *  TRUE if only containing valid characters, or FALSE otherwise.
+ *    TRUE if $host only contains safe characters; FALSE otherwise.
  */
 function drupal_valid_http_host($host) {
   return preg_match('/^\[?(?:[a-zA-Z0-9-:\]_]+\.?)+$/', $host);
 }
 
 /**
+ * Initializes the configuration.
+ *
  * Loads the configuration and sets the base URL, cookie domain, and
  * session name correctly.
  */
@@ -531,30 +536,29 @@
 }
 
 /**
- * Returns and optionally sets the filename for a system item (module,
- * theme, etc.). The filename, whether provided, cached, or retrieved
- * from the database, is only returned if the file exists.
+ * Returns and optionally sets the file name for a system item.
+ *
+ * Filenames and their locations are cached in this function, and
+ * filenames for system items (module, theme, etc.), whether provided,
+ * cached, or retrieved from the database, are only returned if the
+ * file exists.
  *
  * This function plays a key role in allowing Drupal's resources (modules
  * and themes) to be located in different places depending on a site's
  * configuration. For example, a module 'foo' may legally be be located
- * in any of these three places:
- *
- * modules/foo/foo.module
- * sites/all/modules/foo/foo.module
- * sites/example.com/modules/foo/foo.module
- *
- * Calling drupal_get_filename('module', 'foo') will give you one of
+ * in any of these three places: modules/foo/foo.module, 
+ * sites/all/modules/foo/foo.module, or 
+ * sites/example.com/modules/foo/foo.module. Calling 
+ * drupal_get_filename('module', 'foo') will give you one of
  * the above, depending on where the module is located.
  *
  * @param $type
- *   The type of the item (i.e. theme, theme_engine, module).
+ *   The type of the item (e.g., theme, theme_engine, module).
  * @param $name
  *   The name of the item for which the filename is requested.
  * @param $filename
  *   The filename of the item if it is to be set explicitly rather
  *   than by consulting the database.
- *
  * @return
  *   The filename of the requested item.
  */
@@ -599,11 +603,11 @@
 }
 
 /**
- * Load the persistent variable table.
+ * Loads the persistent variable table.
  *
  * The variable table is composed of values that have been saved in the table
- * with variable_set() as well as those explicitly specified in the configuration
- * file.
+ * with variable_set() as well as those explicitly specified in the
+ * configuration file.
  */
 function variable_initialize($conf = array()) {
   // NOTE: caching the variables improves performance by 20% when serving cached pages.
@@ -623,7 +627,7 @@
 }
 
 /**
- * Return a persistent variable.
+ * Returns a persistent variable.
  *
  * @param $name
  *   The name of the variable to return.
@@ -639,7 +643,7 @@
 }
 
 /**
- * Set a persistent variable.
+ * Sets a persistent variable.
  *
  * @param $name
  *   The name of the variable to set.
@@ -658,7 +662,7 @@
 }
 
 /**
- * Unset a persistent variable.
+ * Unsets a persistent variable.
  *
  * @param $name
  *   The name of the variable to undefine.
@@ -675,7 +679,7 @@
 }
 
 /**
- * Retrieve the current page from the cache.
+ * Retrieves the current page from the cache.
  *
  * Note: we do not serve cached pages to authenticated users, or to anonymous
  * users when $_SESSION is non-empty. $_SESSION may contain status messages
@@ -683,7 +687,8 @@
  * specific content that should not be cached and displayed to other users.
  *
  * @return
- *   The cache object, if the page was found in the cache, NULL otherwise.
+ *   The cache object, if the page was found in the cache and is cacheable,
+ *   NULL otherwise.
  */
 function drupal_page_get_cache() {
   global $base_root;
@@ -694,12 +699,12 @@
 }
 
 /**
- * Determine the cacheability of the current page.
+ * Determines the cacheability of the current page.
  *
  * @param $allow_caching
- *  Set to FALSE if you want to prevent this page to get cached.
+ *   Set to FALSE if you want to prevent this page from getting cached.
  * @return
- *  TRUE if the current page can be cached, FALSE otherwise.
+ *   TRUE if the current page can be cached, FALSE otherwise.
  */
 function drupal_page_is_cacheable($allow_caching = NULL) {
   $allow_caching_static = &drupal_static(__FUNCTION__, TRUE);
@@ -712,14 +717,14 @@
 }
 
 /**
- * Includes a file with the provided type and name. This prevents
- * including a theme, engine, module, etc., more than once.
+ * Includes a file with the provided type and name.
+ *
+ * Prevents including a theme, engine, module, etc., more than once.
  *
  * @param $type
  *   The type of item to load (i.e. theme, theme_engine, module).
  * @param $name
  *   The name of the item to load.
- *
  * @return
  *   TRUE if the item is loaded or has already been loaded.
  */
@@ -743,7 +748,7 @@
 }
 
 /**
- * Set an HTTP response header for the current page.
+ * Sets an HTTP response header for the current page.
  *
  * Note: When sending a Content-Type header, always include a 'charset' type,
  * too. This is necessary to avoid security bugs (e.g. UTF-7 XSS).
@@ -789,14 +794,14 @@
 }
 
 /**
- * Get the HTTP response headers for the current page.
+ * Gets the HTTP response headers for the current page.
  *
  * @param $name
- *   An HTTP header name. If omitted, all headers are returned as name/value
- *   pairs. If an array value is FALSE, the header has been unset.
+ *   The name of an HTTP header name to return, or NULL to return all headers.
  * @return
- *   A string containing the header value, or FALSE if the header has been set,
- *   or NULL if the header has not been set.
+ *   Array of headers currently set for the page in $name is NULL. If $name
+ *   is not NULL, returns the corresponding component of the headers, or NULL
+ *   if it does not exist.
  */
 function drupal_get_header($name = NULL) {
   $headers = drupal_set_header();
@@ -810,8 +815,16 @@
 }
 
 /**
+ * Returns the preferred (lower-case) header name or header name array.
+ *
  * Header names are case-insensitive, but for maximum compatibility they should
  * follow "common form" (see RFC 2617, section 4.2).
+ *
+ * @param $name
+ *    Name of the header to regularize.
+ * @return
+ *    Array of all previously-regularized header names, if $name is missing;
+ *    regularized $name if it is set.
  */
 function _drupal_set_preferred_header_name($name = NULL) {
   static $header_names = array();
@@ -823,14 +836,16 @@
 }
 
 /**
- * Send the HTTP response headers previously set using drupal_set_header().
- * Add default headers, unless they have been replaced or unset using
+ * Sends the HTTP response headers previously set using drupal_set_header().
+ *
+ * Adds default headers, unless they have been replaced or unset using
  * drupal_set_header().
  *
  * @param $default_headers
- *   An array of headers as name/value pairs.
- * @param $single
- *   If TRUE and headers have already be sent, send only the specified header.
+ *   An array of default headers as name/value pairs.
+ * @param $only_default
+ *   If TRUE and headers have already been sent, send the passed-in
+ *   $default_headers instead of any previously-set headers.
  */
 function drupal_send_headers($default_headers = array(), $only_default = FALSE) {
   $headers_sent = &drupal_static(__FUNCTION__, FALSE);
@@ -860,13 +875,13 @@
 }
 
 /**
- * Set HTTP headers in preparation for a page response.
+ * Sets HTTP headers in preparation for a page response.
  *
  * Authenticated users are always given a 'no-cache' header, and will fetch a
  * fresh page on every request. This prevents authenticated users from seeing
  * locally cached pages.
  *
- * Also give each page a unique ETag. This will force clients to include both
+ * Also gives each page a unique ETag. This will force clients to include both
  * an If-Modified-Since header and an If-None-Match header when doing
  * conditional requests for the page (required by RFC 2616, section 13.3.4),
  * making the validation more robust. This is a workaround for a bug in Mozilla
@@ -903,7 +918,7 @@
 }
 
 /**
- * Set HTTP headers in preparation for a cached page response.
+ * Sets HTTP headers in preparation for a cached page response.
  *
  * The headers allow as much as possible in proxies and browsers without any
  * particular knowledge about the pages. Modules can override these headers
@@ -1009,6 +1024,10 @@
  *   The object to which the elements are appended.
  * @param $field
  *   The attribute of $obj whose value should be unserialized.
+ * @return
+ *   $obj, with elements from the unserialized attribute $obj->$field
+ *   added as additional attributes. Existing attributes with the same
+ *   keys are not overwritten.
  */
 function drupal_unpack($obj, $field = 'data') {
   if ($obj->$field && $data = unserialize($obj->$field)) {
@@ -1022,7 +1041,7 @@
 }
 
 /**
- * Encode special characters in a plain-text string for display as HTML.
+ * Encodes special characters in a plain-text string for display as HTML.
  *
  * Uses drupal_validate_utf8 to prevent cross site scripting attacks on
  * Internet Explorer 6.
@@ -1065,6 +1084,8 @@
 }
 
 /**
+ * Returns the request URI, generated in a web-server-independent manner.
+ *
  * Since $_SERVER['REQUEST_URI'] is only available on Apache, we
  * generate an equivalent using other environment variables.
  */
@@ -1091,7 +1112,7 @@
 }
 
 /**
- * Log a system message.
+ * Logs a system message.
  *
  * @param $type
  *   The category to which this message belongs.
@@ -1149,22 +1170,19 @@
 }
 
 /**
- * Set a message which reflects the status of the performed operation.
- *
- * If the function is called with no arguments, this function returns all set
- * messages without clearing them.
+ * Sets a message which reflects the status of the performed operation.
  *
  * @param $message
- *   The message should begin with a capital letter and always ends with a
- *   period '.'.
+ *   The message to set -- it should begin with a capital letter and end with a
+ *   period '.'. May be omitted to obtain a list of all previously-set messages,
+ *   without adding or deleting messages.
  * @param $type
- *   The type of the message. One of the following values are possible:
- *   - 'status'
- *   - 'warning'
- *   - 'error'
+ *   The type of the message: 'status', 'warning', or 'error'.
  * @param $repeat
- *   If this is FALSE and the message is already set, then the message won't
+ *   If FALSE and the message is already set, then the message won't
  *   be repeated.
+ * @return
+ *   Array of all currently-set system messages.
  */
 function drupal_set_message($message = NULL, $type = 'status', $repeat = TRUE) {
   if ($message) {
@@ -1185,17 +1203,17 @@
 }
 
 /**
- * Return all messages that have been set.
+ * Returns all messages that have been set.
  *
  * @param $type
  *   (optional) Only return messages of this type.
  * @param $clear_queue
- *   (optional) Set to FALSE if you do not want to clear the messages queue
+ *   (optional) Set to FALSE if you do not want to clear the message queue.
  * @return
- *   An associative array, the key is the message type, the value an array
- *   of messages. If the $type parameter is passed, you get only that type,
- *   or an empty array if there are no such messages. If $type is not passed,
- *   all message types are returned, or an empty array if none exist.
+ *   An associative array, where the key is the message type and the
+ *   value is an array of messages. If the $type parameter is used,
+ *   only that type of message is returned. An empty array is returned
+ *   if there are no messages or no messages of the desired type.
  */
 function drupal_get_messages($type = NULL, $clear_queue = TRUE) {
   if ($messages = drupal_set_message()) {
@@ -1218,7 +1236,7 @@
 }
 
 /**
- * Check to see if an IP address has been blocked.
+ * Checks to see if an IP address has been blocked.
  *
  * Blocked IP addresses are stored in the database by default. However for
  * performance reasons we allow an override in settings.php. This allows us
@@ -1260,25 +1278,29 @@
 }
 
 /**
- * A string describing a phase of Drupal to load. Each phase adds to the
- * previous one, so invoking a later phase automatically runs the earlier
- * phases too. The most important usage is that if you want to access the
- * Drupal database from a script without loading anything else, you can
- * include bootstrap.inc, and call drupal_bootstrap(DRUPAL_BOOTSTRAP_DATABASE).
+ * Returns a string describing a phase of Drupal to load.
+ * 
+ * Each phase adds to the previous one, so invoking a later phase
+ * automatically runs the earlier phases too. The most important usage
+ * is that if you want to access the Drupal database from a script
+ * without loading anything else, you can include bootstrap.inc, and
+ * call drupal_bootstrap(DRUPAL_BOOTSTRAP_DATABASE).
  *
  * @param $phase
  *   A constant. Allowed values are:
- *     DRUPAL_BOOTSTRAP_CONFIGURATION: initialize configuration.
- *     DRUPAL_BOOTSTRAP_EARLY_PAGE_CACHE: try to call a non-database cache fetch routine.
- *     DRUPAL_BOOTSTRAP_DATABASE: initialize database layer.
- *     DRUPAL_BOOTSTRAP_ACCESS: identify and reject banned hosts.
- *     DRUPAL_BOOTSTRAP_SESSION: initialize session handling.
- *     DRUPAL_BOOTSTRAP_VARIABLES: initialize variable handling.
- *     DRUPAL_BOOTSTRAP_LATE_PAGE_CACHE: load bootstrap.inc and module.inc, start
- *       the variable system and try to serve a page from the cache.
- *     DRUPAL_BOOTSTRAP_LANGUAGE: identify the language used on the page.
- *     DRUPAL_BOOTSTRAP_PATH: set $_GET['q'] to Drupal path of request.
- *     DRUPAL_BOOTSTRAP_FULL: Drupal is fully loaded, validate and fix input data.
+ *   - DRUPAL_BOOTSTRAP_CONFIGURATION: initialize configuration.
+ *   - DRUPAL_BOOTSTRAP_EARLY_PAGE_CACHE: try to call a non-database
+ *     cache fetch routine.
+ *   - DRUPAL_BOOTSTRAP_DATABASE: initialize database layer.
+ *   - DRUPAL_BOOTSTRAP_ACCESS: identify and reject banned hosts.
+ *   - DRUPAL_BOOTSTRAP_SESSION: initialize session handling.
+ *   - DRUPAL_BOOTSTRAP_VARIABLES: initialize variable handling.
+ *   - DRUPAL_BOOTSTRAP_LATE_PAGE_CACHE: load bootstrap.inc and module.inc,
+ *     start the variable system, and try to serve a page from the cache.
+ *   - DRUPAL_BOOTSTRAP_LANGUAGE: identify the language used on the page.
+ *   - DRUPAL_BOOTSTRAP_PATH: set $_GET['q'] to Drupal path of request.
+ *   - DRUPAL_BOOTSTRAP_FULL: Drupal is fully loaded, validate and fix input
+ *     data.
  */
 function drupal_bootstrap($phase = NULL) {
   $phases = &drupal_static(__FUNCTION__ . '_phases', array(
@@ -1306,16 +1328,18 @@
 }
 
 /**
- * Return the current bootstrap phase for this Drupal process. The
- * current phase is the one most recently completed by
- * drupal_bootstrap().
+ * Returns the current bootstrap phase for this Drupal process.
  *
- * @see drupal_bootstrap
+ * The current phase is the one most recently completed by
+ * drupal_bootstrap().
  */
 function drupal_get_bootstrap_phase() {
   return drupal_bootstrap();
 }
 
+/**
+ * Internal function: Actually performs the desired bootstrap phase.
+ */
 function _drupal_bootstrap($phase) {
   global $conf, $user;
 
@@ -1431,8 +1455,8 @@
 /**
  * Enables use of the theme system without requiring database access.
  *
- * Loads and initializes the theme system for site installs, updates and when
- * the site is in maintenance mode. This also applies when the database fails.
+ * Loads and initializes the theme system for site installs, updates,
+ * when database loading fails, and when the site is in maintenance mode.
  *
  * @see _drupal_maintenance_theme()
  */
@@ -1442,8 +1466,9 @@
 }
 
 /**
- * Return the name of the localization function. Use in code that needs to
- * run both during installation and normal operation.
+ * Returns the name of the localization function.
+ *
+ * Use in code that needs to run both during installation and normal operation.
  */
 function get_t() {
   static $t;
@@ -1456,7 +1481,7 @@
 }
 
 /**
- *  Choose a language for the current page, based on site and user preferences.
+ * Chooses a language for the current page, based on site and user preferences.
  */
 function drupal_language_initialize() {
   global $language, $user;
@@ -1473,9 +1498,10 @@
 }
 
 /**
- * Get a list of languages set up indexed by the specified key
+ * Gets a list of set-up languages, indexed by the specified key.
  *
- * @param $field The field to index the list with.
+ * @param $field
+ *    The field to index the list with.
  */
 function language_list($field = 'language') {
   $languages = &drupal_static(__FUNCTION__);
@@ -1508,10 +1534,12 @@
 }
 
 /**
- * Default language used on the site
+ * Returns the default language used on the site.
  *
  * @param $property
- *   Optional property of the language object to return
+ *   Property of the language object to return, or NULL to return all.
+ * @return
+ *   Language object for the default language, or a single property of it.
  */
 function language_default($property = NULL) {
   $language = variable_get('language_default', (object) array('language' => 'en', 'name' => 'English', 'native' => 'English', 'direction' => 0, 'enabled' => 1, 'plurals' => 0, 'formula' => '', 'domain' => '', 'prefix' => '', 'weight' => 0, 'javascript' => ''));
@@ -1519,6 +1547,8 @@
 }
 
 /**
+ * Returns the proxy-adjusted IP address being used to access the site.
+ *
  * If Drupal is behind a reverse proxy, we use the X-Forwarded-For header
  * instead of $_SERVER['REMOTE_ADDR'], which would be the IP address of
  * the proxy server, and not the client's. If Drupal is run in a cluster
@@ -1566,7 +1596,7 @@
  */
 
 /**
- * Get the schema definition of a table, or the whole database schema.
+ * Gets the schema definition of a table, or the whole database schema.
  *
  * The returned schema will include any modifications made by any
  * module that implements hook_schema_alter().
@@ -1575,6 +1605,8 @@
  *   The name of the table. If not given, the schema of all tables is returned.
  * @param $rebuild
  *   If true, the schema will be rebuilt instead of retrieved from the cache.
+ * @return
+ *   Array of all database table schemas, or the schema for a particular table.
  */
 function drupal_get_schema($table = NULL, $rebuild = FALSE) {
   static $schema = array();
@@ -1649,7 +1681,7 @@
  */
 
 /**
- * Confirm that a function is available.
+ * Confirms that a function is available.
  *
  * If the function is already available, this function does nothing.
  * If the function is not available, it tries to load the file where the
@@ -1689,7 +1721,7 @@
 }
 
 /**
- * Confirm that an interface is available.
+ * Confirms that an interface is available.
  *
  * This function parallels drupal_function_exists(), but is rarely
  * called directly. Instead, it is registered as an spl_autoload()
@@ -1705,7 +1737,7 @@
 }
 
 /**
- * Confirm that a class is available.
+ * Confirms that a class is available.
  *
  * This function parallels drupal_function_exists(), but is rarely
  * called directly. Instead, it is registered as an spl_autoload()
@@ -1721,7 +1753,7 @@
 }
 
 /**
- * Helper to check for a resource in the registry.
+ * Helper function: checks for a resource in the registry.
  *
  * @param $type
  *   The type of resource we are looking up, or one of the constants
@@ -1797,7 +1829,7 @@
 }
 
 /**
- * Rescan all enabled modules and rebuild the registry.
+ * Rescans all enabled modules and rebuilds the registry.
  *
  * Rescans all code in modules or includes directory, storing a mapping of
  * each function, file, and hook implementation in the database.
@@ -1812,7 +1844,7 @@
  */
 
 /**
- * Central static variable storage.
+ * Resets and/or retrieves centrally-stored static variables.
  *
  * @param $name
  *   Globally unique name for the variable. For a function with only one static,
@@ -1826,7 +1858,6 @@
  *   Resetting every variable should only be used, for example, for running
  *   unit tests with a clean environment. Should be used only though via
  *   function drupal_static_reset().
- *
  * @return
  *   Returns a variable by reference if $reset is FALSE.
  */
@@ -1854,7 +1885,7 @@
 }
 
 /**
- * Reset one or all centrally stored static variable(s).
+ * Resets one or all centrally-stored static variable(s).
  *
  * @param $name
  *   Name of the static variable to reset. Omit to reset all variables.