Index: includes/bootstrap.inc
===================================================================
RCS file: /cvs/drupal/drupal/includes/bootstrap.inc,v
retrieving revision 1.460
diff -u -p -r1.460 bootstrap.inc
--- includes/bootstrap.inc	30 Dec 2010 04:36:53 -0000	1.460
+++ includes/bootstrap.inc	1 Jan 2011 17:50:37 -0000
@@ -162,8 +162,7 @@ define('DRUPAL_BOOTSTRAP_PAGE_HEADER', 5
 define('DRUPAL_BOOTSTRAP_LANGUAGE', 6);
 
 /**
- * Final bootstrap phase: Drupal is fully loaded; validate and fix
- * input data.
+ * Final bootstrap phase: Drupal is fully loaded; validate and fix input data.
  */
 define('DRUPAL_BOOTSTRAP_FULL', 7);
 
@@ -178,8 +177,9 @@ define('DRUPAL_ANONYMOUS_RID', 1);
 define('DRUPAL_AUTHENTICATED_RID', 2);
 
 /**
- * The number of bytes in a kilobyte. For more information, visit
- * http://en.wikipedia.org/wiki/Kilobyte.
+ * The number of bytes in a kilobyte.
+ *
+ * For more information, visit http://en.wikipedia.org/wiki/Kilobyte.
  */
 define('DRUPAL_KILOBYTE', 1024);
 
@@ -248,8 +248,10 @@ define('REGISTRY_WRITE_LOOKUP_CACHE', 2)
 define('DRUPAL_PHP_FUNCTION_PATTERN', '[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*');
 
 /**
- * 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.
@@ -262,10 +264,11 @@ function timer_start($name) {
 }
 
 /**
- * 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.
  */
@@ -285,10 +288,11 @@ function timer_read($name) {
 }
 
 /**
- * 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).
@@ -312,7 +316,7 @@ function timer_stop($name) {
 }
 
 /**
- * Find the appropriate configuration directory.
+ * Finds the appropriate configuration directory.
  *
  * Try finding a matching configuration directory by stripping the website's
  * hostname from left to right and pathname from right to left. The first
@@ -365,13 +369,14 @@ function timer_stop($name) {
  * accessed on development servers.
  *
  * @param $require_settings
- *   Only configuration directories with an existing settings.php file
- *   will be recognized. Defaults to TRUE. During initial installation,
+ *   (optional) Only configuration directories with an existing settings.php
+ *   file will be recognized. Defaults to TRUE. During initial installation,
  *   this is set to FALSE so that Drupal can detect a matching directory,
  *   then create a new settings.php file in it.
  * @param reset
- *   Force a full search for matching directories even if one had been
- *   found previously.
+ *   (optional) Force a full search for matching directories even if one had
+ *   been found previously.
+ *
  * @return
  *   The path of the matching directory.
  */
@@ -409,7 +414,7 @@ function conf_path($require_settings = T
 }
 
 /**
- * Set appropriate server variables needed for command line scripts to work.
+ * Sets appropriate server variables needed for command line scripts to work.
  *
  * This function can be called by command line scripts before bootstrapping
  * Drupal, to ensure that the page loads with the desired server parameters.
@@ -471,7 +476,7 @@ function drupal_override_server_variable
 }
 
 /**
- * Initialize PHP environment.
+ * Initializes PHP environment.
  */
 function drupal_environment_initialize() {
   if (!isset($_SERVER['HTTP_REFERER'])) {
@@ -530,7 +535,7 @@ function drupal_environment_initialize()
 }
 
 /**
- * Validate that a hostname (for example $_SERVER['HTTP_HOST']) is safe.
+ * Validates that a hostname (for example $_SERVER['HTTP_HOST']) is safe.
  *
  * @return
  *  TRUE if only containing valid characters, or FALSE otherwise.
@@ -540,8 +545,9 @@ function drupal_valid_http_host($host) {
 }
 
 /**
- * Loads the configuration and sets the base URL, cookie domain, and
- * session name correctly.
+ * Loads the configuration.
+ *
+ * Also sets the base URL, cookie domain, and session name correctly.
  */
 function drupal_settings_initialize() {
   global $base_url, $base_path, $base_root;
@@ -627,8 +633,9 @@ function drupal_settings_initialize() {
 }
 
 /**
- * Returns and optionally sets the filename for a system item (module,
- * theme, etc.). The filename, whether provided, cached, or retrieved
+ * Returns and optionally sets the filename for a module, theme, etc.
+ *
+ * The filename, whether provided, cached, or retrieved
  * from the database, is only returned if the file exists.
  *
  * This function plays a key role in allowing Drupal's resources (modules
@@ -723,11 +730,20 @@ function drupal_get_filename($type, $nam
 }
 
 /**
- * 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.
+ *
+ * @param $conf
+ *   (optional) An array of variables to merge with the variables in the
+ *   database and configuration file. The array keys are the variable names and
+ *   the array values are the variable values.
+ *
+ * @return
+ *   An array of variables. The array keys are the variable names and the array
+ *   values are the variable values.
  */
 function variable_initialize($conf = array()) {
   // NOTE: caching the variables improves performance by 20% when serving
@@ -769,7 +785,8 @@ function variable_initialize($conf = arr
  * @param $name
  *   The name of the variable to return.
  * @param $default
- *   The default value to use if this variable has never been set.
+ *   (optional) The default value to use if this variable has never been set.
+ *   Defaults to NULL.
  *
  * @return
  *   The value of the variable.
@@ -834,7 +851,7 @@ function variable_del($name) {
 }
 
 /**
- * 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
@@ -866,10 +883,10 @@ function drupal_page_get_cache($check_on
 }
 
 /**
- * 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.
+ *   (optional) Set to FALSE if you want to prevent this page to get cached.
  *
  * @return
  *   TRUE if the current page can be cached, FALSE otherwise.
@@ -885,7 +902,7 @@ function drupal_page_is_cacheable($allow
 }
 
 /**
- * Invoke a bootstrap hook in all bootstrap modules that implement it.
+ * Invokes a bootstrap hook in all bootstrap modules that implement it.
  *
  * @param $hook
  *   The name of the bootstrap hook to invoke.
@@ -907,8 +924,9 @@ function bootstrap_invoke_all($hook) {
 }
 
 /**
- * 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.
+ *
+ * This prevents including a theme, engine, module, etc., more than once.
  *
  * @param $type
  *   The type of item to load (i.e. theme, theme_engine, module).
@@ -940,7 +958,7 @@ function drupal_load($type, $name) {
 }
 
 /**
- * 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).
@@ -952,7 +970,8 @@ function drupal_load($type, $name) {
  *   If $name is 'Status', this is expected to be a status code followed by a
  *   reason phrase, e.g. "404 Not Found".
  * @param $append
- *   Whether to append the value to an existing header or to replace it.
+ *   (optional) Whether to append the value to an existing header or to replace
+ *   it. Defaults to FALSE.
  */
 function drupal_add_http_header($name, $value, $append = FALSE) {
   // The headers as name/value pairs.
@@ -976,11 +995,12 @@ function drupal_add_http_header($name, $
 }
 
 /**
- * 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.
+ *   (optional) 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.
+ *
  * @return
  *   A string containing the header value, or FALSE if the header has been set,
  *   or NULL if the header has not been set.
@@ -997,8 +1017,17 @@ function drupal_get_http_header($name = 
 }
 
 /**
+ * Sets the preferred header name.
+ *
  * Header names are case-insensitive, but for maximum compatibility they should
  * follow "common form" (see RFC 2617, section 4.2).
+ *
+ * @param $name
+ *   (optional) The header name to set. If ommitted, an array of all header
+ *   names, that have been set is returned.
+ *
+ * @return
+ *   If $name is omitted, an array of all header names, that have been set.
  */
 function _drupal_set_preferred_header_name($name = NULL) {
   static $header_names = array();
@@ -1010,14 +1039,16 @@ function _drupal_set_preferred_header_na
 }
 
 /**
- * Send the HTTP response headers previously set using drupal_add_http_header().
- * Add default headers, unless they have been replaced or unset using
+ * Sends the HTTP response headers previously set by drupal_add_http_header().
+ *
+ * Also adds default headers, unless they have been replaced or unset using
  * drupal_add_http_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.
+ *   (optional) An array of headers as name/value pairs.
+ * @param $only_default
+ *   (optional) If TRUE and headers have already be sent, send only the
+ *   specified header.
  */
 function drupal_send_headers($default_headers = array(), $only_default = FALSE) {
   $headers_sent = &drupal_static(__FUNCTION__, FALSE);
@@ -1047,7 +1078,7 @@ function drupal_send_headers($default_he
 }
 
 /**
- * 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
@@ -1090,7 +1121,7 @@ function drupal_page_header() {
 }
 
 /**
- * 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
@@ -1099,6 +1130,9 @@ function drupal_page_header() {
  * If the request is conditional (using If-Modified-Since and If-None-Match),
  * and the conditions match those currently in the cache, a 304 Not Modified
  * response is sent.
+ *
+ * @param $cache
+ *   A cache object as returned by cache_get().
  */
 function drupal_serve_page_from_cache(stdClass $cache) {
   // Negotiate whether to use compression.
@@ -1195,6 +1229,9 @@ function drupal_serve_page_from_cache(st
 
 /**
  * Define the critical hooks that force modules to always be loaded.
+ *
+ * @return
+ *   An array of bootstrap hooks.
  */
 function bootstrap_hooks() {
   return array('boot', 'exit', 'watchdog', 'language_init');
@@ -1206,7 +1243,11 @@ function bootstrap_hooks() {
  * @param $obj
  *   The object to which the elements are appended.
  * @param $field
- *   The attribute of $obj whose value should be unserialized.
+ *   (optional) The attribute of $obj whose value should be unserialized.
+ *   Defaults to 'data'.
+ *
+ * @return
+ *   The object, with the appended elements.
  */
 function drupal_unpack($obj, $field = 'data') {
   if ($obj->$field && $data = unserialize($obj->$field)) {
@@ -1356,17 +1397,17 @@ function drupal_unpack($obj, $field = 'd
  * However tempting it is, custom data from user input or other non-code
  * sources should not be passed through t(). Doing so leads to the following
  * problems and errors:
- *  - The t() system doesn't support updates to existing strings. When user
- *    data is updated, the next time it's passed through t(), a new record is
- *    created instead of an update. The database bloats over time and any
- *    existing translations are orphaned with each update.
- *  - The t() system assumes any data it receives is in English. User data may
- *    be in another language, producing translation errors.
- *  - The "Built-in interface" text group in the locale system is used to
- *    produce translations for storage in .po files. When non-code strings are
- *    passed through t(), they are added to this text group, which is rendered
- *    inaccurate since it is a mix of actual interface strings and various user
- *    input strings of uncertain origin.
+ * - The t() system doesn't support updates to existing strings. When user
+ *   data is updated, the next time it's passed through t(), a new record is
+ *   created instead of an update. The database bloats over time and any
+ *   existing translations are orphaned with each update.
+ * - The t() system assumes any data it receives is in English. User data may
+ *   be in another language, producing translation errors.
+ * - The "Built-in interface" text group in the locale system is used to
+ *   produce translations for storage in .po files. When non-code strings are
+ *   passed through t(), they are added to this text group, which is rendered
+ *   inaccurate since it is a mix of actual interface strings and various user
+ *   input strings of uncertain origin.
  * Instead, translation of these data can be done through the locale system,
  * either directly through hook_local() or through helper functions provided by
  * contributed modules.
@@ -1384,19 +1425,21 @@ function drupal_unpack($obj, $field = 'd
  * @param $string
  *   A string containing the English string to translate.
  * @param $args
- *   An associative array of replacements to make after translation. Incidences
- *   of any key in this array are replaced with the corresponding value. Based
- *   on the first character of the key, the value is escaped and/or themed:
- *    - !variable: inserted as is
- *    - @variable: escape plain text to HTML (using check_plain())
- *    - %variable: escape text and theme as a placeholder for user-submitted
- *      content (using check_plain() + drupal_placeholder())
+ *   (optional) An associative array of replacements to make after translation.
+ *   Incidences of any key in this array are replaced with the corresponding
+ *   value. Based on the first character of the key, the value is escaped and/or
+ *   themed:
+ *   - !variable: inserted as is
+ *   - @variable: escape plain text to HTML (using check_plain())
+ *   - %variable: escape text and theme as a placeholder for user-submitted
+ *     content (using check_plain() + drupal_placeholder())
  * @param $options
- *   An associative array of additional options, with the following keys:
- *     - 'langcode' (defaults to the current language) The language code to
- *       translate to a language other than what is used to display the page.
- *     - 'context' (defaults to the empty context) The context the source string
- *       belongs to.
+ *   (optional) An associative array of additional options, with the following
+ *   keys:
+ *   - langcode: (defaults to the current language) The language code to
+ *     translate to a language other than what is used to display the page.
+ *   - context: (defaults to the empty context) The context the source string
+ *     belongs to.
  *
  * @return
  *   The translated string.
@@ -1457,7 +1500,7 @@ function t($string, array $args = array(
 }
 
 /**
- * Encode special characters in a plain-text string for display as HTML.
+ * Encodes special characters in a plain-text string for display as HTML.
  *
  * Also validates strings as UTF-8 to prevent cross site scripting attacks on
  * Internet Explorer 6.
@@ -1496,6 +1539,7 @@ function check_plain($text) {
  *
  * @param $text
  *   The text to check.
+ *
  * @return
  *   TRUE if the text is valid UTF-8, FALSE if not.
  */
@@ -1510,8 +1554,13 @@ function drupal_validate_utf8($text) {
 }
 
 /**
+ * Returns the request URI.
+ *
  * Since $_SERVER['REQUEST_URI'] is only available on Apache, we
  * generate an equivalent using other environment variables.
+ *
+ * @return
+ *   A string containing the request URI.
  */
 function request_uri() {
 
@@ -1536,7 +1585,7 @@ function request_uri() {
 }
 
 /**
- * Log an exception.
+ * Logs an exception.
  *
  * This is a wrapper function for watchdog() which automatically decodes an
  * exception.
@@ -1546,15 +1595,16 @@ function request_uri() {
  * @param $exception
  *   The exception that is going to be logged.
  * @param $message
- *   The message to store in the log. If empty, a text that contains all useful
- *   information about the passed in exception is used.
+ *   (optional) The message to store in the log. If empty, a text that contains
+ *   all useful information about the passed in exception is used.
  * @param $variables
- *   Array of variables to replace in the message on display. Defaults to the
- *   return value of drupal_decode_exception().
+ *   (optional) Array of variables to replace in the message on display.
+ *   Defaults to the return value of drupal_decode_exception().
  * @param $severity
- *   The severity of the message, as per RFC 3164.
+ *   (optional) The severity of the message, as per RFC 3164. Defaults to
+ *   WATCHDOG_ERROR.
  * @param $link
- *   A link to associate with the message.
+ *   (optional) A link to associate with the message.
  *
  * @see watchdog()
  * @see drupal_decode_exception()
@@ -1577,7 +1627,7 @@ function watchdog_exception($type, Excep
 }
 
 /**
- * Log a system message.
+ * Logs a system message.
  *
  * @param $type
  *   The category to which this message belongs. Can be any string, but the
@@ -1589,14 +1639,13 @@ function watchdog_exception($type, Excep
  *   the variables argument to declare the value of the placeholders.
  *   See t() for documentation on how $message and $variables interact.
  * @param $variables
- *   Array of variables to replace in the message on display or
- *   NULL if message is already translated or not possible to
- *   translate.
+ *   (optional) Array of variables to replace in the message on display or NULL
+ *   if message is already translated or not possible to translate.
  * @param $severity
- *   The severity of the message, as per RFC 3164. Possible values are
- *   WATCHDOG_ERROR, WATCHDOG_WARNING, etc.
+ *   (optional) The severity of the message, as per RFC 3164. Possible values
+ *   are WATCHDOG_ERROR, WATCHDOG_WARNING, etc. Defaults to WATCHDOG_NOTICE. 
  * @param $link
- *   A link to associate with the message.
+ *   (optional) A link to associate with the message.
  *
  * @see watchdog_severity_levels()
  * @see hook_watchdog()
@@ -1637,22 +1686,28 @@ function watchdog($type, $message, $vari
 }
 
 /**
- * Set a message which reflects the status of the performed operation.
+ * Sets 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.
  *
  * @param $message
- *   The message should begin with a capital letter and always ends with a
- *   period '.'.
+ *   (optional) The message should begin with a capital letter and always ends
+ *   with a period '.'. If omitted, returns an array of all previously set
+ *   messages.
  * @param $type
- *   The type of the message. One of the following values are possible:
+ *   (optional) The type of the message. One of the following values are
+ *   possible:
  *   - 'status'
  *   - 'warning'
  *   - 'error'
+ *   Defaults to 'status'.
  * @param $repeat
- *   If this is FALSE and the message is already set, then the message won't
- *   be repeated.
+ *   (optional) If this is FALSE and the message is already set, then the
+ *   message won't be repeated. Defaults to TRUE.
+ *
+ * @return
+ *   If $message is omitted, an array of all previously set messages.
  */
 function drupal_set_message($message = NULL, $type = 'status', $repeat = TRUE) {
   if ($message) {
@@ -1673,12 +1728,13 @@ function drupal_set_message($message = N
 }
 
 /**
- * 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 messages 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,
@@ -1706,7 +1762,9 @@ function drupal_get_messages($type = NUL
 }
 
 /**
- * Get the title of the current page, for display on the page and in the title bar.
+ * Gets the title of the current page.
+ *
+ * This is used for display on the page and in the title bar.
  *
  * @return
  *   The current page's title.
@@ -1723,13 +1781,15 @@ function drupal_get_title() {
 }
 
 /**
- * Set the title of the current page, for display on the page and in the title bar.
+ * Sets the title of the current page.
+ *
+ * This title is displayed on the page and in the title bar.
  *
  * @param $title
- *   Optional string value to assign to the page title; or if set to NULL
- *   (default), leaves the current title unchanged.
+ *   (optional) String value to assign to the page title. Defaults to NULL,
+ *   which leaves the current title unchanged.
  * @param $output
- *   Optional flag - normally should be left as CHECK_PLAIN. Only set to
+ *   (optional) Sanitation flag. Defaults to CHECK_PLAIN. Only set to
  *   PASS_THROUGH if you have already removed any possibly dangerous code
  *   from $title using a function like check_plain() or filter_xss(). With this
  *   flag the string will be passed through unchanged.
@@ -1748,7 +1808,7 @@ function drupal_set_title($title = NULL,
 }
 
 /**
- * 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
@@ -1757,7 +1817,8 @@ function drupal_set_title($title = NULL,
  *
  * @param $ip
  *   IP address to check.
- * @return bool
+ *
+ * @return
  *   TRUE if access is denied, FALSE if access is allowed.
  */
 function drupal_is_denied($ip) {
@@ -1782,7 +1843,7 @@ function drupal_is_denied($ip) {
 }
 
 /**
- * Handle denied users.
+ * Handles denied users.
  *
  * @param $ip
  *   IP address to check. Prints a message and exits if access is denied.
@@ -1805,6 +1866,9 @@ function drupal_block_denied($ip) {
  *
  * @param $count
  *   The number of characters (bytes) to return in the string.
+ *
+ * @return
+ *   A string of highly randomized bytes.
  */
 function drupal_random_bytes($count)  {
   // $random_state does not use drupal_static as it stores random bytes.
@@ -1848,7 +1912,7 @@ function drupal_random_bytes($count)  {
 }
 
 /**
- * Calculate a base-64 encoded, URL-safe sha-256 hmac.
+ * Calculates a base-64 encoded, URL-safe sha-256 hmac.
  *
  * @param $data
  *   String to be validated with the hmac.
@@ -1866,7 +1930,7 @@ function drupal_hmac_base64($data, $key)
 }
 
 /**
- * Calculate a base-64 encoded, URL-safe sha-256 hash.
+ * Calculates a base-64 encoded, URL-safe sha-256 hash.
  *
  * @param $data
  *   String to be hashed.
@@ -1927,6 +1991,12 @@ function drupal_array_merge_deep() {
  * - call_user_func_array('drupal_array_merge_deep', $arrays_to_merge);
  * - drupal_array_merge_deep_array($arrays_to_merge);
  *
+ * @param $arrays
+ *   An array of arrays to be merged.
+ *
+ * @return
+ *   The merged array.
+ *
  * @see drupal_array_merge_deep()
  */
 function drupal_array_merge_deep_array($arrays) {
@@ -1957,7 +2027,8 @@ function drupal_array_merge_deep_array($
 /**
  * Generates a default anonymous $user object.
  *
- * @return Object - the user object.
+ * @return
+ *   A user object.
  */
 function drupal_anonymous_user() {
   $user = new stdClass();
@@ -1970,20 +2041,23 @@ function drupal_anonymous_user() {
 }
 
 /**
- * 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
+ * Bootstraps Drupal to a certain bootstrap phase.
+ *
+ * Each phase is a constant 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 the DRUPAL_BOOTSTRAP_* constants.
+ *   (optional) A constant. Allowed values are the DRUPAL_BOOTSTRAP_* constants.
+ *   Defaults to NULL, which simply returns the most recently completed phase.
  * @param $new_phase
- *   A boolean, set to FALSE if calling drupal_bootstrap from inside a
- *   function called from drupal_bootstrap (recursion).
+ *   (optional) A boolean, set to FALSE if calling drupal_bootstrap from inside a
+ *   function called from drupal_bootstrap (recursion). Defaults to TRUE.
+ *
  * @return
  *   The most recently completed phase.
- *
  */
 function drupal_bootstrap($phase = NULL, $new_phase = TRUE) {
   // Not drupal_static(), because does not depend on any run-time information.
@@ -2062,7 +2136,10 @@ function drupal_bootstrap($phase = NULL,
 }
 
 /**
- * Return the time zone of the current user.
+ * Returns the time zone of the current user.
+ *
+ * @return
+ *   A string containing the current user's time zone.
  */
 function drupal_get_user_timezone() {
   global $user;
@@ -2124,7 +2201,7 @@ function _drupal_exception_handler($exce
 }
 
 /**
- * Bootstrap configuration: Setup script environment and load settings.php.
+ * Bootstrap configuration: Sets up script environment and loads settings.php.
  */
 function _drupal_bootstrap_configuration() {
   // Set the Drupal custom error handler.
@@ -2139,7 +2216,7 @@ function _drupal_bootstrap_configuration
 }
 
 /**
- * Bootstrap page cache: Try to serve a page from cache.
+ * Bootstrap page cache: Tries to serve a page from cache.
  */
 function _drupal_bootstrap_page_cache() {
   global $user;
@@ -2195,7 +2272,7 @@ function _drupal_bootstrap_page_cache() 
 }
 
 /**
- * Bootstrap database: Initialize database system and register autoload functions.
+ * Bootstrap database: Initializes database system and registers autoload functions.
  */
 function _drupal_bootstrap_database() {
   // Redirect the user to the installation script if Drupal has not been
@@ -2247,7 +2324,7 @@ function _drupal_bootstrap_database() {
 }
 
 /**
- * Bootstrap variables: Load system variables and all enabled bootstrap modules.
+ * Bootstrap variables: Loads system variables and all enabled bootstrap modules.
  */
 function _drupal_bootstrap_variables() {
   global $conf;
@@ -2264,7 +2341,7 @@ function _drupal_bootstrap_variables() {
 }
 
 /**
- * Bootstrap page header: Invoke hook_boot(), initialize locking system, and send default HTTP headers.
+ * Bootstrap page header: Invokes hook_boot(), initializes locking system, and sends default HTTP headers.
  */
 function _drupal_bootstrap_page_header() {
   bootstrap_invoke_all('boot');
@@ -2287,6 +2364,8 @@ function drupal_get_bootstrap_phase() {
 }
 
 /**
+ * Generates a valid simpletest prefix.
+ *
  * Checks the current User-Agent string to see if this is an internal request
  * from SimpleTest. If so, returns the test prefix for this test.
  *
@@ -2324,7 +2403,13 @@ function drupal_valid_test_ua() {
 }
 
 /**
- * Generate a user agent string with a HMAC and timestamp for simpletest.
+ * Generates a user agent string with a HMAC and timestamp for simpletest.
+ *
+ * @param $prefix
+ *   A string containing the simpletest prefix.
+ *
+ * @return
+ *   A User-Agent string.
  */
 function drupal_generate_test_ua($prefix) {
   global $drupal_hash_salt;
@@ -2356,15 +2441,22 @@ function drupal_maintenance_theme() {
 }
 
 /**
- * Return TRUE if a Drupal installation is currently being attempted.
+ * Returns TRUE if a Drupal installation is currently being attempted.
+ *
+ * @return
+ *   A boolean indicating whether an installation is currently being attempted.
  */
 function drupal_installation_attempted() {
   return defined('MAINTENANCE_MODE') && MAINTENANCE_MODE == 'install';
 }
 
 /**
- * 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.
+ *
+ * @return
+ *   A string containing either the localization function. 
  */
 function get_t() {
   static $t;
@@ -2377,7 +2469,7 @@ function get_t() {
 }
 
 /**
- * Initialize all the defined language types.
+ * Initializes all the defined language types.
  */
 function drupal_language_initialize() {
   $types = language_types();
@@ -2402,7 +2494,7 @@ function drupal_language_initialize() {
 }
 
 /**
- * The built-in language types.
+ * Returns an array of the built-in language types.
  *
  * @return
  *   An array of key-values pairs where the key is the language type and the
@@ -2417,23 +2509,35 @@ function drupal_language_types() {
 }
 
 /**
- * Return true if there is more than one language enabled.
+ * Returns TRUE if there is more than one language enabled.
+ *
+ * @return
+ *   A boolean indicating whether there is more than one language enabled.
  */
 function drupal_multilingual() {
   return variable_get('language_count', 1) > 1;
 }
 
 /**
- * Return an array of the available language types.
+ * Returns an array of the available language types.
+ *
+ * @return
+ *   An array of the available language types. The keys are the language types
+ *   and the values are booleans indicating the configurability of the language
+ *   type.
  */
 function language_types() {
   return array_keys(variable_get('language_types', drupal_language_types()));
 }
 
 /**
- * Get a list of languages set up indexed by the specified key
+ * Gets a list of languages set up indexed by the specified key.
  *
- * @param $field The field to index the list with.
+ * @param $field
+ *   (optional) The field to index the list with. Defaults to 'language'.
+ *
+ * @return
+ *   An array of languages.
  */
 function language_list($field = 'language') {
   $languages = &drupal_static(__FUNCTION__);
@@ -2472,10 +2576,15 @@ function language_list($field = 'languag
 }
 
 /**
- * Default language used on the site
+ * Returns the default language used on the site.
  *
  * @param $property
- *   Optional property of the language object to return
+ *   (optional) Property of the language object to return. If omitted, the whole
+ *   language object is returned.
+ *
+ * @return
+ *   Depending on whether $property was set, the whole language object, or the
+ *   specified property.
  */
 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' => ''));
@@ -2532,7 +2641,7 @@ function request_path() {
 }
 
 /**
- * Return a component of the current Drupal path.
+ * Returns a component of the current Drupal path.
  *
  * When viewing a page at the path "admin/structure/types", for example, arg(0)
  * returns "admin", arg(1) returns "structure", and arg(2) returns "types".
@@ -2544,10 +2653,12 @@ function request_path() {
  * node on a node page, please use menu_get_object() instead.
  *
  * @param $index
- *   The index of the component, where each component is separated by a '/'
- *   (forward-slash), and where the first component has an index of 0 (zero).
+ *   (optional) The index of the component, where each component is separated by
+ *   a '/' (forward-slash), and where the first component has an index of 0
+ *   (zero). If omitted, an array of all components is returned.
  * @param $path
- *   A path to break into components. Defaults to the path of the current page.
+ *   (optional) A path to break into components. Defaults to the path of the
+ *   current page.
  *
  * @return
  *   The component specified by $index, or NULL if the specified component was
@@ -2581,6 +2692,8 @@ function arg($index = NULL, $path = NULL
 }
 
 /**
+ * Returns the client's IP address.
+ *
  * 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. The actual header name can be
@@ -2630,15 +2743,21 @@ function ip_address() {
  */
 
 /**
- * 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().
  *
  * @param $table
- *   The name of the table. If not given, the schema of all tables is returned.
+ *   (optional) 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.
+ *   (optional) If TRUE, the schema will be rebuilt instead of retrieved from
+ *   the cache. Defaults to FALSE.
+ *
+ * @return
+ *   An array containing the schema definition of the specified table or an
+ *   array of schema definitions keyed by table name.
  */
 function drupal_get_schema($table = NULL, $rebuild = FALSE) {
   static $schema = array();
@@ -2707,13 +2826,14 @@ function drupal_get_schema($table = NULL
  */
 
 /**
- * Confirm that an interface is available.
+ * Confirms that an interface is available.
  *
  * This function is rarely called directly. Instead, it is registered as an
  * spl_autoload()  handler, and PHP calls it for us when necessary.
  *
  * @param $interface
  *   The name of the interface to check or load.
+ *
  * @return
  *   TRUE if the interface is currently available, FALSE otherwise.
  */
@@ -2722,13 +2842,14 @@ function drupal_autoload_interface($inte
 }
 
 /**
- * Confirm that a class is available.
+ * Confirms that a class is available.
  *
  * This function is rarely called directly. Instead, it is registered as an
  * spl_autoload()  handler, and PHP calls it for us when necessary.
  *
  * @param $class
  *   The name of the class to check or load.
+ *
  * @return
  *   TRUE if the class is currently available, FALSE otherwise.
  */
@@ -2737,15 +2858,16 @@ function drupal_autoload_class($class) {
 }
 
 /**
- * Helper to check for a resource in the registry.
+ * Checks for a resource in the registry.
  *
  * @param $type
  *   The type of resource we are looking up, or one of the constants
  *   REGISTRY_RESET_LOOKUP_CACHE or REGISTRY_WRITE_LOOKUP_CACHE, which
  *   signal that we should reset or write the cache, respectively.
  * @param $name
- *   The name of the resource, or NULL if either of the REGISTRY_* constants
- *   is passed in.
+ *   (optional) The name of the resource, or NULL if either of the REGISTRY_*
+ *   constants is passed in. Defaults to NULL.
+ *
  * @return
  *   TRUE if the resource was found, FALSE if not.
  *   NULL if either of the REGISTRY_* constants is passed in as $type.
@@ -2817,7 +2939,7 @@ function _registry_check_code($type, $na
 }
 
 /**
- * Rescan all enabled modules and rebuild the registry.
+ * Rescans all enabled modules and rebuilds the registry.
  *
  * Rescans all code in modules or includes directories, storing the location of
  * each interface or class in the database.
@@ -2828,7 +2950,7 @@ function registry_rebuild() {
 }
 
 /**
- * Update the registry based on the latest files listed in the database.
+ * Updates the registry based on the latest files listed in the database.
  *
  * This function should be used when system_rebuild_module_data() does not need
  * to be called, because it is already known that the list of files in the
@@ -2950,13 +3072,13 @@ function registry_update() {
  *   is recommended. For a function with multiple static variables add a
  *   distinguishing suffix to the function name for each one.
  * @param $default_value
- *   Optional default value.
+ *   (optional) The default value.
  * @param $reset
- *   TRUE to reset a specific named variable, or all variables if $name is NULL.
- *   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() and the return value should not be used in
- *   this case.
+ *   (optional) TRUE to reset a specific named variable, or all variables if
+ *   $name is NULL. 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() and the return value should not be used
+ *   in this case. Defaults to FALSE.
  *
  * @return
  *   Returns a variable by reference.
@@ -2997,17 +3119,22 @@ function &drupal_static($name, $default_
 }
 
 /**
- * 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.
+ *   (optional) Name of the static variable to reset. Omit to reset all
+ *   variables.
  */
 function drupal_static_reset($name = NULL) {
   drupal_static($name, NULL, TRUE);
 }
 
 /**
- * Detect whether the current script is running in a command-line environment.
+ * Detects whether the current script is running in a command-line environment.
+ *
+ * @return
+ *   A boolean indicating whether the current script is running in a
+ *   command-line environment.
  */
 function drupal_is_cli() {
   return (!isset($_SERVER['SERVER_SOFTWARE']) && (php_sapi_name() == 'cli' || (is_numeric($_SERVER['argc']) && $_SERVER['argc'] > 0)));
@@ -3015,26 +3142,27 @@ function drupal_is_cli() {
 
 /**
  * Formats text for emphasized display in a placeholder inside a sentence.
+ *
  * Used automatically by t().
  *
  * @param $text
  *   The text to format (plain-text).
  *
  * @return
- *   The formatted text (html).
+ *   The formatted text (HTML).
  */
 function drupal_placeholder($text) {
   return '<em class="placeholder">' . check_plain($text) . '</em>';
 }
 
 /**
- * Register a function for execution on shutdown.
+ * Registers a function for execution on shutdown.
  *
  * Wrapper for register_shutdown_function() that catches thrown exceptions to
  * avoid "Exception thrown without a stack frame in Unknown".
  *
  * @param $callback
- *   The shutdown function to register.
+ *   (optional) The shutdown function to register.
  * @param ...
  *   Additional arguments to pass to the shutdown function.
  *
@@ -3063,7 +3191,7 @@ function &drupal_register_shutdown_funct
 }
 
 /**
- * Internal function used to execute registered shutdown functions.
+ * Executes registered shutdown functions.
  */
 function _drupal_shutdown_function() {
   $callbacks = &drupal_register_shutdown_function();