From 1630397c14a3aef9b408b6ee083a5147126c963c Mon Sep 17 00:00:00 2001
From: Lars Toomre <ltoomre@23809.no-reply.drupal.org>
Date: Sun, 6 Nov 2011 16:26:23 -0500
Subject: [PATCH] Issue 1333470 by Lars Toomre: Missing variable type hinting
 from common.inc.

---
 core/includes/common.inc |  550 +++++++++++++++++++++++-----------------------
 1 files changed, 276 insertions(+), 274 deletions(-)

diff --git a/core/includes/common.inc b/core/includes/common.inc
index 4229d52..80f7cab 100644
--- a/core/includes/common.inc
+++ b/core/includes/common.inc
@@ -158,9 +158,9 @@ define('DRUPAL_CACHE_GLOBAL', 0x0008);
 /**
  * Add content to a specified region.
  *
- * @param $region
+ * @param string $region
  *   Page region the content is added to.
- * @param $data
+ * @param mixed $data
  *   Content to be added.
  */
 function drupal_add_region_content($region = NULL, $data = NULL) {
@@ -175,10 +175,10 @@ function drupal_add_region_content($region = NULL, $data = NULL) {
 /**
  * Get assigned content for a given region.
  *
- * @param $region
+ * @param string $region
  *   A specified region to fetch content for. If NULL, all regions will be
  *   returned.
- * @param $delimiter
+ * @param string $delimiter
  *   Content to be inserted between imploded array elements.
  */
 function drupal_get_region_content($region = NULL, $delimiter = ' ') {
@@ -207,7 +207,7 @@ function drupal_get_region_content($region = NULL, $delimiter = ' ') {
  * table contains the name of the current profile, and we can call variable_get()
  * to determine what one is active.
  *
- * @return $profile
+ * @return string $profile
  *   The name of the install profile.
  */
 function drupal_get_profile() {
@@ -227,7 +227,7 @@ function drupal_get_profile() {
 /**
  * Set the breadcrumb trail for the current page.
  *
- * @param $breadcrumb
+ * @param array $breadcrumb
  *   Array of links, starting with "home" and proceeding up to but not including
  *   the current page.
  */
@@ -259,14 +259,14 @@ function drupal_get_breadcrumb() {
  * This function can be called as long as the headers aren't sent. Pass no
  * arguments (or NULL for both) to retrieve the currently stored elements.
  *
- * @param $data
+ * @param array $data
  *   A renderable array. If the '#type' key is not set then 'html_tag' will be
  *   added as the default '#type'.
- * @param $key
+ * @param string $key
  *   A unique string key to allow implementations of hook_html_head_alter() to
  *   identify the element in $data. Required if $data is not NULL.
  *
- * @return
+ * @return array
  *   An array of all stored HEAD elements.
  *
  * @see theme_html_tag()
@@ -335,9 +335,9 @@ function drupal_get_html_head() {
  *
  * This function can be called as long the HTML header hasn't been sent.
  *
- * @param $url
+ * @param string $url
  *   An internal system path or a fully qualified external URL of the feed.
- * @param $title
+ * @param string $title
  *   The title of the feed.
  */
 function drupal_add_feed($url = NULL, $title = '') {
@@ -361,7 +361,7 @@ function drupal_add_feed($url = NULL, $title = '') {
 /**
  * Get the feed URLs for the current page.
  *
- * @param $delimiter
+ * @param string $delimiter
  *   A delimiter to split feeds by.
  */
 function drupal_get_feeds($delimiter = "\n") {
@@ -378,15 +378,15 @@ function drupal_get_feeds($delimiter = "\n") {
 /**
  * Process a URL query parameter array to remove unwanted elements.
  *
- * @param $query
+ * @param array $query
  *   (optional) An array to be processed. Defaults to $_GET.
- * @param $exclude
+ * @param array $exclude
  *   (optional) A list of $query array keys to remove. Use "parent[child]" to
  *   exclude nested items. Defaults to array('q').
- * @param $parent
+ * @param string $parent
  *   Internal use only. Used to build the $query array key for nested items.
  *
- * @return
+ * @return array
  *   An array containing query parameters, which can be used for url().
  */
 function drupal_get_query_parameters(array $query = NULL, array $exclude = array('q'), $parent = '') {
@@ -423,10 +423,10 @@ function drupal_get_query_parameters(array $query = NULL, array $exclude = array
 /**
  * Split an URL-encoded query string into an array.
  *
- * @param $query
+ * @param string $query
  *   The query string to split.
  *
- * @return
+ * @return array
  *   An array of url decoded couples $param_name => $value.
  */
 function drupal_get_query_array($query) {
@@ -446,12 +446,12 @@ function drupal_get_query_array($query) {
  * This differs from http_build_query() as we need to rawurlencode() (instead of
  * urlencode()) all query parameters.
  *
- * @param $query
+ * @param array $query
  *   The query parameter array to be processed, e.g. $_GET.
- * @param $parent
+ * @param string $parent
  *   Internal use only. Used to build the $query array key for nested items.
  *
- * @return
+ * @return string
  *   A rawurlencoded string which can be used as or appended to the URL query
  *   string.
  *
@@ -532,10 +532,10 @@ function drupal_get_destination() {
  * needs to be parsed into an associative query parameter array in
  * $options['query'] and the fragment into $options['fragment'].
  *
- * @param $url
+ * @param string $url
  *   The URL string to parse, f.e. $_GET['destination'].
  *
- * @return
+ * @return array
  *   An associative array containing the keys:
  *   - 'path': The path of the URL. If the given $url is external, this includes
  *     the scheme and host.
@@ -602,7 +602,7 @@ function drupal_parse_url($url) {
  * Note that url() takes care of calling this function, so a path passed to that
  * function should not be encoded in advance.
  *
- * @param $path
+ * @param string $path
  *   The Drupal path to encode.
  */
 function drupal_encode_path($path) {
@@ -631,11 +631,11 @@ function drupal_encode_path($path) {
  * This function ends the request; use it instead of a return in your menu
  * callback.
  *
- * @param $path
+ * @param string $path
  *   A Drupal path or a full URL.
- * @param $options
+ * @param array $options
  *   An associative array of additional URL options to pass to url().
- * @param $http_response_code
+ * @param int $http_response_code
  *   Valid values for an actual "goto" as per RFC 2616 section 10.3 are:
  *   - 301 Moved Permanently (the recommended value for most redirects)
  *   - 302 Found (default in Drupal and PHP, sometimes used for spamming search
@@ -717,7 +717,7 @@ function drupal_access_denied() {
  * This is a flexible and powerful HTTP client implementation. Correctly
  * handles GET, POST, PUT or any other HTTP requests. Handles redirects.
  *
- * @param $url
+ * @param string $url
  *   A string containing a fully qualified URI.
  * @param array $options
  *   (optional) An array that can have one or more of the following elements:
@@ -1066,9 +1066,9 @@ function fix_gpc_magic() {
  *
  * Empty e-mail addresses are allowed. See RFC 2822 for details.
  *
- * @param $mail
+ * @param string $mail
  *   A string containing an e-mail address.
- * @return
+ * @return bool
  *   TRUE if the address is in a valid format.
  */
 function valid_email_address($mail) {
@@ -1081,11 +1081,11 @@ function valid_email_address($mail) {
  * This function should only be used on actual URLs. It should not be used for
  * Drupal menu paths, which can contain arbitrary characters.
  * Valid values per RFC 3986.
- * @param $url
+ * @param string $url
  *   The URL to verify.
- * @param $absolute
+ * @param bool $absolute
  *   Whether the URL is absolute (beginning with a scheme such as "http:").
- * @return
+ * @return bool
  *   TRUE if the URL is in a valid format.
  */
 function valid_url($url, $absolute = FALSE) {
@@ -1119,14 +1119,14 @@ function valid_url($url, $absolute = FALSE) {
 /**
  * Register an event for the current visitor to the flood control mechanism.
  *
- * @param $name
+ * @param string $name
  *   The name of an event.
- * @param $window
+ * @param int $window
  *   Optional number of seconds before this event expires. Defaults to 3600 (1
  *   hour). Typically uses the same value as the flood_is_allowed() $window
  *   parameter. Expired events are purged on cron run to prevent the flood table
  *   from growing indefinitely.
- * @param $identifier
+ * @param string $identifier
  *   Optional identifier (defaults to the current user's IP address).
  */
 function flood_register_event($name, $window = 3600, $identifier = NULL) {
@@ -1146,9 +1146,9 @@ function flood_register_event($name, $window = 3600, $identifier = NULL) {
 /**
  * Make the flood control mechanism forget about an event for the current visitor.
  *
- * @param $name
+ * @param string $name
  *   The name of an event.
- * @param $identifier
+ * @param string $identifier
  *   Optional identifier (defaults to the current user's IP address).
  */
 function flood_clear_event($name, $identifier = NULL) {
@@ -1168,17 +1168,17 @@ function flood_clear_event($name, $identifier = NULL) {
  * a certain number of times in a time window. This function verifies that the
  * current user has not exceeded this threshold.
  *
- * @param $name
+ * @param string $name
  *   The unique name of the event.
- * @param $threshold
+ * @param int $threshold
  *   The maximum number of times each user can do this event per time window.
- * @param $window
+ * @param int $window
  *   Number of seconds in the time window for this event (default is 3600
  *   seconds, or 1 hour).
- * @param $identifier
+ * @param string $identifier
  *   Unique identifier of the current user. Defaults to their IP address.
  *
- * @return
+ * @return bool
  *   TRUE if the user is allowed to proceed. FALSE if they have exceeded the
  *   threshold and should not be allowed to proceed.
  */
@@ -1213,10 +1213,10 @@ function flood_is_allowed($name, $threshold, $window = 3600, $identifier = NULL)
  * be a plain-text string for passing to t(), l(), drupal_attributes(), or
  * another function that will call check_plain() separately.
  *
- * @param $uri
+ * @param string $uri
  *   A plain-text URI that might contain dangerous protocols.
  *
- * @return
+ * @return string
  *   A plain-text URI stripped of dangerous protocols. As with all plain-text
  *   strings, this return value must not be output to an HTML page without
  *   check_plain() being called on it. However, it can be passed to functions
@@ -1258,10 +1258,10 @@ function drupal_strip_dangerous_protocols($uri) {
 /**
  * Strips dangerous protocols (e.g. 'javascript:') from a URI and encodes it for output to an HTML attribute value.
  *
- * @param $uri
+ * @param string $uri
  *   A plain-text URI that might contain dangerous protocols.
  *
- * @return
+ * @return string
  *   A URI stripped of dangerous protocols and encoded for output to an HTML
  *   attribute value. Because it is already encoded, it should not be set as a
  *   value within a $attributes array passed to drupal_attributes(), because
@@ -1302,13 +1302,13 @@ function filter_xss_admin($string) {
  * - Makes sure no HTML tags contain URLs with a disallowed protocol (e.g.
  *   javascript:).
  *
- * @param $string
+ * @param string $string
  *   The string with raw HTML in it. It will be stripped of everything that can
  *   cause an XSS attack.
- * @param $allowed_tags
+ * @param array $allowed_tags
  *   An array of allowed tags.
  *
- * @return
+ * @return string
  *   An XSS safe version of $string, or an empty string if $string is not
  *   valid UTF-8.
  *
@@ -1353,13 +1353,13 @@ function filter_xss($string, $allowed_tags = array('a', 'em', 'strong', 'cite',
 /**
  * Processes an HTML tag.
  *
- * @param $m
+ * @param array $m
  *   An array with various meaning depending on the value of $store.
  *   If $store is TRUE then the array contains the allowed tags.
  *   If $store is FALSE then the array has one element, the HTML tag to process.
- * @param $store
+ * @param bool $store
  *   Whether to store $m.
- * @return
+ * @return string
  *   If the element isn't allowed, an empty string. Otherwise, the cleaned up
  *   version of the HTML element.
  */
@@ -1424,7 +1424,7 @@ function _filter_xss_split($m, $store = FALSE) {
 /**
  * Processes a string of HTML attributes.
  *
- * @return
+ * @return array
  *   Cleaned up version of the HTML attributes.
  */
 function _filter_xss_attributes($attr) {
@@ -1528,14 +1528,14 @@ function _filter_xss_attributes($attr) {
 /**
  * Processes an HTML attribute value and ensures it does not contain an URL with a disallowed protocol (e.g. javascript:).
  *
- * @param $string
+ * @param string $string
  *   The string with the attribute value.
- * @param $decode
+ * @param bool $decode
  *   (Deprecated) Whether to decode entities in the $string. Set to FALSE if the
  *   $string is in plain text, TRUE otherwise. Defaults to TRUE. This parameter
  *   is deprecated and will be removed in Drupal 8. To process a plain-text URI,
  *   call drupal_strip_dangerous_protocols() or check_url() instead.
- * @return
+ * @return string
  *   Cleaned up and HTML-escaped version of $string.
  */
 function filter_xss_bad_protocol($string, $decode = TRUE) {
@@ -1606,7 +1606,7 @@ function format_rss_item($title, $link, $description, $args = array()) {
 /**
  * Format XML elements.
  *
- * @param $array
+ * @param array $array
  *   An array where each item represents an element and is either a:
  *   - (key => value) pair (<key>value</key>)
  *   - Associative array with fields:
@@ -1616,7 +1616,9 @@ function format_rss_item($title, $link, $description, $args = array()) {
  *
  * In both cases, 'value' can be a simple string, or it can be another array
  * with the same format as $array itself for nesting.
- */
+ *
+ * @return string
+*/
 function format_xml_elements($array) {
   $output = '';
   foreach ($array as $key => $value) {
@@ -1662,17 +1664,17 @@ function format_xml_elements($array) {
  *     array('%old-type' => $info->old_type, '%new-type' => $info->new_type)));
  * @endcode
  *
- * @param $count
+ * @param int $count
  *   The item count to display.
- * @param $singular
+ * @param string $singular
  *   The string for the singular case. Please make sure it is clear this is
  *   singular, to ease translation (e.g. use "1 new comment" instead of "1 new").
  *   Do not use @count in the singular string.
- * @param $plural
+ * @param string $plural
  *   The string for the plural case. Please make sure it is clear this is plural,
  *   to ease translation. Use @count in place of the item count, as in "@count
  *   new comments".
- * @param $args
+ * @param array $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:
@@ -1682,13 +1684,13 @@ function format_xml_elements($array) {
  *      content (check_plain + drupal_placeholder)
  *   Note that you do not need to include @count in this array.
  *   This replacement is done automatically for the plural case.
- * @param $options
+ * @param array $options
  *   An associative array of additional options, with the following keys:
  *     - 'langcode' (default to the current language) The language code to
  *       translate to a language other than what is used to display the page.
  *     - 'context' (default to the empty context) The context the source string
  *       belongs to.
- * @return
+ * @return array
  *   A translated string.
  */
 function format_plural($count, $singular, $plural, array $args = array(), array $options = array()) {
@@ -1720,10 +1722,10 @@ function format_plural($count, $singular, $plural, array $args = array(), array
 /**
  * Parse a given byte count.
  *
- * @param $size
+ * @param int $size
  *   A size expressed as a number of bytes with optional SI or IEC binary unit
  *   prefix (e.g. 2, 3K, 5MB, 10G, 6GiB, 8 bytes, 9mbytes).
- * @return
+ * @return int
  *   An integer representation of the size in bytes.
  */
 function parse_size($size) {
@@ -1741,12 +1743,12 @@ function parse_size($size) {
 /**
  * Generate a string representation for the given byte count.
  *
- * @param $size
+ * @param int $size
  *   A size in bytes.
- * @param $langcode
+ * @param string $langcode
  *   Optional language code to translate to a language other than what is used
  *   to display the page.
- * @return
+ * @return string
  *   A translated string representation of the size.
  */
 function format_size($size, $langcode = NULL) {
@@ -1780,14 +1782,14 @@ function format_size($size, $langcode = NULL) {
 /**
  * Format a time interval with the requested granularity.
  *
- * @param $timestamp
+ * @param int $timestamp
  *   The length of the interval in seconds.
- * @param $granularity
+ * @param int $granularity
  *   How many different units to display in the string.
- * @param $langcode
+ * @param string $langcode
  *   Optional language code to translate to a language other than
  *   what is used to display the page.
- * @return
+ * @return string
  *   A translated string representation of the interval.
  */
 function format_interval($timestamp, $granularity = 2, $langcode = NULL) {
@@ -1819,9 +1821,9 @@ function format_interval($timestamp, $granularity = 2, $langcode = NULL) {
 /**
  * Formats a date, using a date type or a custom date format string.
  *
- * @param $timestamp
+ * @param integer $timestamp
  *   A UNIX timestamp to format.
- * @param $type
+ * @param string $type
  *   (optional) The format to use, one of:
  *   - 'short', 'medium', or 'long' (the corresponding built-in date formats).
  *   - The name of a date type defined by a module in hook_date_format_types(),
@@ -1829,19 +1831,19 @@ function format_interval($timestamp, $granularity = 2, $langcode = NULL) {
  *   - The machine name of an administrator-defined date format.
  *   - 'custom', to use $format.
  *   Defaults to 'medium'.
- * @param $format
+ * @param string $format
  *   (optional) If $type is 'custom', a PHP date format string suitable for
  *   input to date(). Use a backslash to escape ordinary text, so it does not
  *   get interpreted as date format characters.
- * @param $timezone
+ * @param string $timezone
  *   (optional) Time zone identifier, as described at
  *   http://php.net/manual/en/timezones.php Defaults to the time zone used to
  *   display the page.
- * @param $langcode
+ * @param string $langcode
  *   (optional) Language code to translate to. Defaults to the language used to
  *   display the page.
  *
- * @return
+ * @return string
  *   A translated date string in the requested format.
  */
 function format_date($timestamp, $type = 'medium', $format = '', $timezone = NULL, $langcode = NULL) {
@@ -1920,7 +1922,7 @@ function format_date($timestamp, $type = 'medium', $format = '', $timezone = NUL
  *
  * Can be used as a callback for RDF mappings.
  *
- * @param $date
+ * @param int $date
  *   A UNIX timestamp.
  * @return string
  *   An ISO8601 formatted date.
@@ -1974,10 +1976,10 @@ function _format_date_callback(array $matches = NULL, $new_langcode = NULL) {
  *
  * @see hook_username_alter()
  *
- * @param $account
+ * @param object $account
  *   The account object for the user whose name is to be formatted.
  *
- * @return
+ * @return string
  *   An unsanitized string with the username to display. The code receiving
  *   this result must ensure that check_plain() is called on it before it is
  *   printed to the page.
@@ -1998,7 +2000,7 @@ function format_username($account) {
  * When creating links in modules, consider whether l() could be a better
  * alternative than url().
  *
- * @param $path
+ * @param string $path
  *   The internal path or external URL being linked to, such as "node/34" or
  *   "http://example.com/foo". A few notes:
  *   - If you provide a full URL, it will be considered an external URL.
@@ -2015,7 +2017,7 @@ function format_username($account) {
  *     then you can either URL encode the query keys and values yourself and
  *     include them in $path, or use $options['query'] to let this function
  *     URL encode them.
- * @param $options
+ * @param array $options
  *   An associative array of additional options, with the following elements:
  *   - 'query': An array of query key/value-pairs (without any URL-encoding) to
  *     append to the URL.
@@ -2052,7 +2054,7 @@ function format_username($account) {
  *   - 'entity': The entity object (such as a node) for which the URL is being
  *     generated. Only set if url() is invoked by entity_uri().
  *
- * @return
+ * @return string
  *   A string containing a URL to the given path.
  */
 function url($path = NULL, array $options = array()) {
@@ -2178,10 +2180,10 @@ function url($path = NULL, array $options = array()) {
  * If a path cannot be assessed by Drupal's menu handler, then we must
  * treat it as potentially insecure.
  *
- * @param $path
+ * @param string $path
  *   The internal path or external URL being linked to, such as "node/34" or
  *   "http://example.com/foo".
- * @return
+ * @return bool
  *   Boolean TRUE or FALSE, where TRUE indicates an external path.
  */
 function url_is_external($path) {
@@ -2195,10 +2197,10 @@ function url_is_external($path) {
 /**
  * Format an attribute string for a HTTP header.
  *
- * @param $attributes
+ * @param array $attributes
  *   An associative array of attributes such as 'rel'.
  *
- * @return
+ * @return string
  *   A ; separated string ready for insertion in a HTTP header. No escaping is
  *   performed for HTML entities, so this string is not safe to be printed.
  *
@@ -2242,10 +2244,10 @@ function drupal_http_header_attributes(array $attributes = array()) {
  *   drupal_attributes(array('onmouseout' => 'window.location="http://malicious.com/";')));
  * @endcode
  *
- * @param $attributes
+ * @param array $attributes
  *   An associative array of key-value pairs to be converted to attributes.
  *
- * @return
+ * @return string
  *   A string ready for insertion in a tag (starts with a space).
  *
  * @ingroup sanitization
@@ -2266,9 +2268,9 @@ function drupal_attributes(array $attributes = array()) {
  * internal links output by modules should be generated by this function if
  * possible.
  *
- * @param $text
+ * @param string $text
  *   The link text for the anchor tag.
- * @param $path
+ * @param string $path
  *   The internal path or external URL being linked to, such as "node/34" or
  *   "http://example.com/foo". After the url() function is called to construct
  *   the URL from $path and $options, the resulting URL is passed through
@@ -2291,7 +2293,7 @@ function drupal_attributes(array $attributes = array()) {
  *     well as the path must match). This element is also used by url().
  *   - Additional $options elements used by the url() function.
  *
- * @return
+ * @return string
  *   An HTML string containing a link to the given path.
  */
 function l($text, $path, array $options = array()) {
@@ -2399,13 +2401,13 @@ function l($text, $path, array $options = array()) {
  * drupal_deliver_html_page() for an example of a delivery callback that
  * respects security.
  *
- * @param $page_callback_result
+ * @param mixed $page_callback_result
  *   The result of a page callback. Can be one of:
  *   - NULL: to indicate no content.
  *   - An integer menu status constant: to indicate an error condition.
  *   - A string of HTML content.
  *   - A renderable array of content.
- * @param $default_delivery_callback
+ * @param string $default_delivery_callback
  *   (Optional) If given, it is the name of a delivery function most likely
  *   to be appropriate for the page request as determined by the calling
  *   function (e.g., menu_execute_active_handler()). If not given, it is
@@ -2438,7 +2440,7 @@ function drupal_deliver_page($page_callback_result, $default_delivery_callback =
 /**
  * Package and send the result of a page callback to the browser as HTML.
  *
- * @param $page_callback_result
+ * @param mixed $page_callback_result
  *   The result of a page callback. Can be one of:
  *   - NULL: to indicate no content.
  *   - An integer menu status constant: to indicate an error condition.
@@ -2578,7 +2580,7 @@ function drupal_page_footer() {
  * In these cases, call drupal_exit() instead. There should rarely be a reason
  * to call exit instead of drupal_exit();
  *
- * @param $destination
+ * @param string $destination
  *   If this function is called from drupal_goto(), then this argument
  *   will be a fully-qualified URL that is the destination of the redirect.
  *   This should be passed along to hook_exit() implementations.
@@ -2602,12 +2604,12 @@ function drupal_exit($destination = NULL) {
  * specified, in which case the output of the function is used for the values
  * instead.
  *
- * @param $array
+ * @param array $array
  *   A linear array.
- * @param $function
+ * @param string $function
  *   A name of a function to apply to all values before output.
  *
- * @return
+ * @return array
  *   An associative array.
  */
 function drupal_map_assoc($array, $function = NULL) {
@@ -2642,7 +2644,7 @@ function drupal_map_assoc($array, $function = NULL) {
  * not possible to reliably ensure that PHP or a security extension will
  * not issue a warning/error if they prevent the use of this function.
  *
- * @param $time_limit
+ * @param int $time_limit
  *   An integer specifying the new time limit, in seconds. A value of 0
  *   indicates unlimited execution time.
  *
@@ -2657,12 +2659,12 @@ function drupal_set_time_limit($time_limit) {
 /**
  * Returns the path to a system item (module, theme, etc.).
  *
- * @param $type
+ * @param string $type
  *   The type of the item (i.e. theme, theme_engine, module, profile).
- * @param $name
+ * @param string $name
  *   The name of the item for which the path is requested.
  *
- * @return
+ * @return string
  *   The path to the requested item.
  */
 function drupal_get_path($type, $name) {
@@ -2691,9 +2693,9 @@ function base_path() {
  * Adding a link will overwrite a prior link with the exact same 'rel' and
  * 'href' attributes.
  *
- * @param $attributes
+ * @param array $attributes
  *   Associative array of element attributes including 'href' and 'rel'.
- * @param $header
+ * @param bool $header
  *   Optional flag to determine if a HTTP 'Link:' header should be sent.
  */
 function drupal_add_html_head_link($attributes, $header = FALSE) {
@@ -2740,7 +2742,7 @@ function drupal_add_html_head_link($attributes, $header = FALSE) {
  * Non-preprocessed files should only be added to the page when they are
  * actually needed.
  *
- * @param $data
+ * @param string $data
  *   (optional) The stylesheet data to be added, depending on what is passed
  *   through to the $options['type'] parameter:
  *   - 'file': The path to the CSS file relative to the base_path(), or a
@@ -2764,7 +2766,7 @@ function drupal_add_html_head_link($attributes, $header = FALSE) {
  *   - 'external': The absolute path to an external CSS file that is not hosted
  *     on the local server. These files will not be aggregated if CSS
  *     aggregation is enabled.
- * @param $options
+ * @param array $options
  *   (optional) A string defining the 'type' of CSS that is being added in the
  *   $data parameter ('file', 'inline', or 'external'), or an array which can
  *   have any or all of the following keys:
@@ -2824,7 +2826,7 @@ function drupal_add_html_head_link($attributes, $header = FALSE) {
  *     should load the CSS item. See drupal_pre_render_conditional_comments()
  *     for details.
  *
- * @return
+ * @return array
  *   An array of queued cascading stylesheets.
  *
  * @see drupal_get_css()
@@ -2901,15 +2903,15 @@ function drupal_add_css($data = NULL, $options = NULL) {
  * responsible for supplying an accompanying RTL CSS file to replace the
  * module's.
  *
- * @param $css
+ * @param array $css
  *   (optional) An array of CSS files. If no array is provided, the default
  *   stylesheets array is used instead.
- * @param $skip_alter
+ * @param bool $skip_alter
  *   (optional) If set to TRUE, this function skips calling drupal_alter() on
  *   $css, useful when the calling function passes a $css array that has already
  *   been altered.
  *
- * @return
+ * @return string
  *   A string of XHTML CSS tags.
  *
  * @see drupal_add_css()
@@ -3016,11 +3018,11 @@ function drupal_sort_css_js($a, $b) {
  * same type, media, and browsers, if needed to accommodate other items in
  * between.
  *
- * @param $css
+ * @param array $css
  *   An array of CSS items, as returned by drupal_add_css(), but after
  *   alteration performed by drupal_get_css().
  *
- * @return
+ * @return array
  *   An array of CSS groups. Each group contains the same keys (e.g., 'media',
  *   'data', etc.) as a CSS item from the $css parameter, with the value of
  *   each key applying to the group as a whole. Each group also contains an
@@ -3103,7 +3105,7 @@ function drupal_group_css($css) {
  * other unnecessary content. Additionally, this functions aggregates inline
  * content together, regardless of the site-wide aggregation setting.
  *
- * @param $css_groups
+ * @param array $css_groups
  *   An array of CSS groups as returned by drupal_group_css(). This function
  *   modifies the group's 'data' property for each group that is aggregated.
  *
@@ -3180,7 +3182,7 @@ function drupal_aggregate_css(&$css_groups) {
  * this function to work correctly even if modules have implemented custom
  * logic for grouping and aggregating files.
  *
- * @param $element
+ * @param array $element
  *   A render array containing:
  *   - '#items': The CSS items as returned by drupal_add_css() and altered by
  *     drupal_get_css().
@@ -3190,7 +3192,7 @@ function drupal_aggregate_css(&$css_groups) {
  *   - '#aggregate_callback': A function to call to aggregate the items within
  *     the groups arranged by the #group_callback function.
  *
- * @return
+ * @return array
  *   A render array that will render to a string of XHTML CSS tags.
  *
  * @see drupal_get_css()
@@ -3376,10 +3378,10 @@ function drupal_pre_render_styles($elements) {
  * period by drupal_delete_file_if_stale(). This ensures that files referenced
  * by a cached page will still be available.
  *
- * @param $css
+ * @param array $css
  *   An array of CSS files to aggregate and compress into one file.
  *
- * @return
+ * @return string
  *   The URI of the CSS cache file, or FALSE if the file could not be saved.
  */
 function drupal_build_css_cache($css) {
@@ -3481,14 +3483,14 @@ function _drupal_build_css_path($matches, $base = NULL) {
  * when CSS aggregation is enabled. This optimization will not apply for
  * color.module enabled themes with CSS aggregation turned off.
  *
- * @param $file
+ * @param string $file
  *   Name of the stylesheet to be processed.
- * @param $optimize
+ * @param ??? $optimize    <== variable type??
  *   Defines if CSS contents should be compressed or not.
- * @param $reset_basepath
+ * @param bool $reset_basepath
  *   Used internally to facilitate recursive resolution of @import commands.
  *
- * @return
+ * @return string
  *   Contents of the stylesheet, including any resolved @import commands.
  */
 function drupal_load_stylesheet($file, $optimize = NULL, $reset_basepath = TRUE) {
@@ -3524,12 +3526,12 @@ function drupal_load_stylesheet($file, $optimize = NULL, $reset_basepath = TRUE)
 /**
  * Process the contents of a stylesheet for aggregation.
  *
- * @param $contents
+ * @param string $contents
  *   The contents of the stylesheet.
- * @param $optimize
+ * @param bool $optimize
  *   (optional) Boolean whether CSS contents should be minified. Defaults to
  *   FALSE.
- * @return
+ * @return string
  *   Contents of the stylesheet including the imported stylesheets.
  */
 function drupal_load_stylesheet_content($contents, $optimize = FALSE) {
@@ -3629,11 +3631,11 @@ function drupal_delete_file_if_stale($uri) {
  * http://www.w3.org/TR/CSS21/syndata.html#characters shows the syntax for valid
  * CSS identifiers (including element names, classes, and IDs in selectors.)
  *
- * @param $identifier
+ * @param string $identifier
  *   The identifier to clean.
- * @param $filter
+ * @param array $filter
  *   An array of string replacements to use on the identifier.
- * @return
+ * @return string
  *   The cleaned identifier.
  */
 function drupal_clean_css_identifier($identifier, $filter = array(' ' => '-', '_' => '-', '/' => '-', '[' => '-', ']' => '')) {
@@ -3659,9 +3661,9 @@ function drupal_clean_css_identifier($identifier, $filter = array(' ' => '-', '_
  * Do not pass one string containing multiple classes as they will be
  * incorrectly concatenated with dashes, i.e. "one two" will become "one-two".
  *
- * @param $class
+ * @param string $class
  *   The class name to clean.
- * @return
+ * @return string
  *   The cleaned class name.
  */
 function drupal_html_class($class) {
@@ -3689,10 +3691,10 @@ function drupal_html_class($class) {
  * To allow reverse-parsing of IDs submitted via Ajax, any multiple consecutive
  * hyphens in the originally passed $id are replaced with a single hyphen.
  *
- * @param $id
+ * @param string $id
  *   The ID to clean.
  *
- * @return
+ * @return string
  *   The cleaned ID.
  */
 function drupal_html_id($id) {
@@ -3774,10 +3776,10 @@ function drupal_html_id($id) {
  * names in this way allows modules to implement certain features, such as
  * drag-and-drop or dynamic Ajax loading, in a theme-independent way.
  *
- * @param $region
+ * @param string $region
  *   The name of the page region (for example, 'page_top' or 'content').
  *
- * @return
+ * @return string
  *   An HTML class that identifies the region (for example, 'region-page-top'
  *   or 'region-content').
  *
@@ -3845,7 +3847,7 @@ function drupal_region_class($region) {
  * Non-preprocessed files should only be added to the page when they are
  * actually needed.
  *
- * @param $data
+ * @param string|array $data
  *   (optional) If given, the value depends on the $options parameter:
  *   - 'file': Path to the file relative to base_path().
  *   - 'inline': The JavaScript code that should be placed in the given scope.
@@ -3858,7 +3860,7 @@ function drupal_region_class($region) {
  *     the Drupal.settings namespace. Items added with a string key will replace
  *     existing settings with that key; items with numeric array keys will be
  *     added to the existing settings array.
- * @param $options
+ * @param string|array $options
  *   (optional) A string defining the type of JavaScript that is being added in
  *   the $data parameter ('file'/'setting'/'inline'/'external'), or an
  *   associative array. JavaScript settings should always pass the string
@@ -3930,7 +3932,7 @@ function drupal_region_class($region) {
  *     should load the JavaScript item. See
  *     drupal_pre_render_conditional_comments() for details.
  *
- * @return
+ * @return array
  *   The current array of JavaScript files, settings, and in-line code,
  *   including Drupal defaults, anything previously added with calls to
  *   drupal_add_js(), and this function call's additions.
@@ -4020,7 +4022,7 @@ function drupal_add_js($data = NULL, $options = NULL) {
 /**
  * Constructs an array of the defaults that are used for JavaScript items.
  *
- * @param $data
+ * @param mixed $data
  *   (optional) The default data parameter for the JavaScript item array.
  * @see drupal_get_js()
  * @see drupal_add_js()
@@ -4056,17 +4058,17 @@ function drupal_js_defaults($data = NULL) {
  * is to add another element to the $javascript array, deriving from
  * drupal_js_defaults(). See locale_js_alter() for an example of this.
  *
- * @param $scope
+ * @param string $scope
  *   (optional) The scope for which the JavaScript rules should be returned.
  *   Defaults to 'header'.
- * @param $javascript
+ * @param array $javascript
  *   (optional) An array with all JavaScript code. Defaults to the default
  *   JavaScript array for the given scope.
- * @param $skip_alter
+ * @param bool $skip_alter
  *   (optional) If set to TRUE, this function skips calling drupal_alter() on
  *   $javascript, useful when the calling function passes a $javascript array
  *   that has already been altered.
- * @return
+ * @return string
  *   All JavaScript code segments and includes for the scope as HTML tags.
  * @see drupal_add_js()
  * @see locale_js_alter()
@@ -4130,7 +4132,7 @@ function drupal_get_js($scope = 'header', $javascript = NULL, $skip_alter = FALS
  * this function to work correctly even if modules have implemented custom
  * logic for grouping and aggregating files.
  *
- * @param $element
+ * @param array $element
  *   A render array containing:
  *   - #items: The JavaScript items as returned by drupal_add_js() and
  *     altered by drupal_get_js().
@@ -4140,7 +4142,7 @@ function drupal_get_js($scope = 'header', $javascript = NULL, $skip_alter = FALS
  *   - #aggregate_callback: A function to call to aggregate the items within
  *     the groups arranged by the #group_callback function.
  *
- * @return
+ * @return array
  *   A render array that will render to a string of JavaScript tags.
  *
  * @see drupal_get_js()
@@ -4255,11 +4257,11 @@ function drupal_pre_render_scripts($elements) {
  * same type and browsers, if needed to accommodate other items in
  * between.
  *
- * @param $javascript
+ * @param array $javascript
  *   An array of JavaScript items, as returned by drupal_add_js(), but after
  *   alteration performed by drupal_get_js().
  *
- * @return
+ * @return array
  *   An array of JavaScript groups. Each group contains the same keys (e.g.,
  *   'data', etc.) as a JavaScript item from the $javascript parameter, with the
  *   value of each key applying to the group as a whole. Each group also
@@ -4330,7 +4332,7 @@ function drupal_group_js($javascript) {
  * download, it also compresses the aggregate files by removing comments,
  * whitespace, and other unnecessary content.
  *
- * @param $js_groups
+ * @param array $js_groups
  *   An array of JavaScript groups as returned by drupal_group_js(). For each
  *   group that is aggregated, this function sets the value of the group's
  *   'data' key to the URI of the aggregate file.
@@ -4382,22 +4384,22 @@ function drupal_aggregate_js(&$js_groups) {
  * );
  * @endcode
  *
- * @param $elements
+ * @param array $elements
  *   The structured array describing the data being rendered.
- * @param $group
+ * @param ??? $group    <== Variable type??
  *   The default group of JavaScript and CSS being added. This is only applied
  *   to the stylesheets and JavaScript items that don't have an explicit group
  *   assigned to them.
- * @param $dependency_check
+ * @param bool $dependency_check
  *   When TRUE, will exit if a given library's dependencies are missing. When
  *   set to FALSE, will continue to add the libraries, even though one or more
  *   dependencies are missing. Defaults to FALSE.
- * @param $every_page
+ * @param bool $every_page
  *   Set to TRUE to indicate that the attachments are added to every page on the
  *   site. Only attachments with the every_page flag set to TRUE can participate
  *   in JavaScript/CSS aggregation.
  *
- * @return
+ * @return bool
  *   FALSE if there were any missing library dependencies; TRUE if all library
  *   dependencies were met.
  *
@@ -4589,7 +4591,7 @@ function drupal_process_attached($elements, $group = JS_DEFAULT, $dependency_che
  *   ),
  * @endcode
  *
- * @param $elements
+ * @param array $elements
  *   A renderable array element having a #states property as described above.
  *
  * @see form_example_states_form()
@@ -4612,11 +4614,11 @@ function drupal_process_states(&$elements) {
  * depending module, without having to add all files of the library separately.
  * Each library is only loaded once.
  *
- * @param $module
+ * @param string $module
  *   The name of the module that registered the library.
- * @param $name
+ * @param string $name
  *   The name of the library to add.
- * @param $every_page
+ * @param bool $every_page
  *   Set to TRUE if this library is added to every page on the site. Only items
  *   with the every_page flag set to TRUE can participate in aggregation.
  *
@@ -4664,13 +4666,13 @@ function drupal_add_library($module, $name, $every_page = NULL) {
  * - Two (or more) modules can still register the same library and use it
  *   without conflicts in case the libraries are loaded on certain pages only.
  *
- * @param $module
+ * @param string $module
  *   The name of a module that registered a library.
- * @param $name
+ * @param string $name
  *   (optional) The name of a registered library to retrieve. By default, all
  *   libraries registered by $module are returned.
  *
- * @return
+ * @return array|false
  *   The definition of the requested library, if $name was passed and it exists,
  *   or FALSE if it does not exist. If no $name was passed, an associative array
  *   of libraries registered by $module is returned (which may be empty).
@@ -4789,34 +4791,34 @@ function drupal_get_library($module, $name = NULL) {
  * clean and readable. It also prevents tabledrag.js from being added twice
  * accidentally.
  *
- * @param $table_id
+ * @param string $table_id
  *   String containing the target table's id attribute. If the table does not
  *   have an id, one will need to be set, such as <table id="my-module-table">.
- * @param $action
+ * @param string $action
  *   String describing the action to be done on the form item. Either 'match'
  *   'depth', or 'order'. Match is typically used for parent relationships.
  *   Order is typically used to set weights on other form elements with the same
  *   group. Depth updates the target element with the current indentation.
- * @param $relationship
+ * @param string $relationship
  *   String describing where the $action variable should be performed. Either
  *   'parent', 'sibling', 'group', or 'self'. Parent will only look for fields
  *   up the tree. Sibling will look for fields in the same group in rows above
  *   and below it. Self affects the dragged row itself. Group affects the
  *   dragged row, plus any children below it (the entire dragged group).
- * @param $group
+ * @param string $group
  *   A class name applied on all related form elements for this action.
- * @param $subgroup
+ * @param string $subgroup
  *   (optional) If the group has several subgroups within it, this string should
  *   contain the class name identifying fields in the same subgroup.
- * @param $source
+ * @param string $source
  *   (optional) If the $action is 'match', this string should contain the class
  *   name identifying what field will be used as the source value when matching
  *   the value in $subgroup.
- * @param $hidden
+ * @param bool $hidden
  *   (optional) The column containing the field elements may be entirely hidden
  *   from view dynamically when the JavaScript is loaded. Set to FALSE if the
  *   column should not be hidden.
- * @param $limit
+ * @param int $limit
  *   (optional) Limit the maximum amount of parenting in this table.
  * @see block-admin-display-form.tpl.php
  * @see theme_menu_overview_form()
@@ -4864,10 +4866,10 @@ function drupal_add_tabledrag($table_id, $action, $relationship, $group, $subgro
  * period by drupal_delete_file_if_stale(). This ensures that files referenced
  * by a cached page will still be available.
  *
- * @param $files
+ * @param array $files
  *   An array of JavaScript files to aggregate and compress into one file.
  *
- * @return
+ * @return string|false
  *   The URI of the cache file, or FALSE if the file could not be saved.
  */
 function drupal_build_js_cache($files) {
@@ -4951,7 +4953,7 @@ function drupal_json_decode($var) {
  * This function should be used for JavaScript callback functions returning
  * data in JSON format. It sets the header for JavaScript output.
  *
- * @param $var
+ * @param mixed $var
  *   (optional) If set, the variable will be converted to JSON and output.
  */
 function drupal_json_output($var = NULL) {
@@ -4966,7 +4968,7 @@ function drupal_json_output($var = NULL) {
 /**
  * Get a salt useful for hardening against SQL injection.
  *
- * @return
+ * @return string
  *   A salt based on information in settings.php, not in the database.
  */
 function drupal_get_hash_salt() {
@@ -4979,7 +4981,7 @@ function drupal_get_hash_salt() {
 /**
  * Ensure the private key variable used to generate tokens is set.
  *
- * @return
+ * @return string
  *   The private key.
  */
 function drupal_get_private_key() {
@@ -4993,7 +4995,7 @@ function drupal_get_private_key() {
 /**
  * Generate a token based on $value, the current user session and private key.
  *
- * @param $value
+ * @param ??? $value    <= variable type??
  *   An additional value to base the token on.
  */
 function drupal_get_token($value = '') {
@@ -5003,13 +5005,13 @@ function drupal_get_token($value = '') {
 /**
  * Validate a token based on $value, the current user session and private key.
  *
- * @param $token
+ * @param ??? $token    <== variable type??
  *   The token to be validated.
- * @param $value
+ * @param ??? $value    <== variable type??
  *   An additional value to base the token on.
- * @param $skip_anonymous
+ * @param bool $skip_anonymous
  *   Set to true to skip token validation for anonymous users.
- * @return
+ * @return bool
  *   True for a valid token, false for an invalid token. When $skip_anonymous
  *   is true, the return value will always be true for anonymous users.
  */
@@ -5131,7 +5133,7 @@ function drupal_page_set_cache() {
  *
  * Do not call this function from test, use $this->cronRun() instead.
  *
- * @return
+ * @return bool
  *   Returns TRUE if ran successfully
  */
 function drupal_cron_run() {
@@ -5333,9 +5335,9 @@ function drupal_system_listing($mask, $directory, $key = 'name', $min_depth = 1)
  * a string or array. We store that and return it later as the block is being
  * displayed.
  *
- * @param $content
+ * @param string|array $content
  *   A string or renderable array representing the body of the page.
- * @return
+ * @return array|null
  *   If called without $content, a renderable array representing the body of
  *   the page.
  */
@@ -5359,8 +5361,8 @@ function drupal_set_page_content($content = NULL) {
 /**
  * #pre_render callback to render #browsers into #prefix and #suffix.
  *
- * @param $elements
- *   A render array with a '#browsers' property. The '#browsers' property can
+ * @param array $elements
+ *   - A render array with a '#browsers' property. The '#browsers' property can
  *   contain any or all of the following keys:
  *   - 'IE': If FALSE, the element is not rendered by Internet Explorer. If
  *     TRUE, the element is rendered by Internet Explorer. Can also be a string
@@ -5381,7 +5383,7 @@ function drupal_set_page_content($content = NULL) {
  *   - To render an element in Internet Explorer 8 and higher and in all other
  *     browsers, '#browsers' can be set to array('IE' => 'gte IE 8').
  *
- * @return
+ * @return array
  *   The passed-in element with markup for conditional comments potentially
  *   added to '#prefix' and '#suffix'.
  */
@@ -5437,13 +5439,13 @@ function drupal_pre_render_conditional_comments($elements) {
  *
  * Doing so during pre_render gives modules a chance to alter the link parts.
  *
- * @param $elements
+ * @param array $elements
  *   A structured array whose keys form the arguments to l():
  *   - #title: The link text to pass as argument to l().
  *   - #href: The URL path component to pass as argument to l().
  *   - #options: (optional) An array of options to pass to l().
  *
- * @return
+ * @return array
  *   The passed-in elements containing a rendered link in '#markup'.
  */
 function drupal_pre_render_link($element) {
@@ -5601,7 +5603,7 @@ function drupal_pre_render_markup($elements) {
 /**
  * Renders the page, including all theming.
  *
- * @param $page
+ * @param string|array $page
  *   A string or array representing the content of a page. The array consists of
  *   the following keys:
  *   - #type: Value is always 'page'. This pushes the theming through page.tpl.php (required).
@@ -5710,9 +5712,9 @@ function drupal_render_page($page) {
  * larger array). If the same array or array element is passed more than once
  * to drupal_render(), it simply returns a NULL value.
  *
- * @param $elements
+ * @param array $elements
  *   The structured array describing the data to be rendered.
- * @return
+ * @return string
  *   The rendered HTML.
  */
 function drupal_render(&$elements) {
@@ -5830,9 +5832,9 @@ function drupal_render(&$elements) {
  * This renders all children of an element using drupal_render() and then
  * joins them together into a single string.
  *
- * @param $element
+ * @param array $element
  *   The structured array whose children shall be rendered.
- * @param $children_keys
+ * @param bool $children_keys
  *   If the keys of the element's children are already known, they can be passed
  *   in to save another run of element_children().
  */
@@ -5856,10 +5858,10 @@ function drupal_render_children(&$element, $children_keys = NULL) {
  * element is shown with show() before rendering, so it will always be rendered
  * even if hide() had been previously used on it.
  *
- * @param $element
+ * @param mixed $element
  *   The element to be rendered.
  *
- * @return
+ * @return mixed
  *   The rendered element.
  *
  * @see drupal_render()
@@ -5890,10 +5892,10 @@ function render(&$element) {
  * rendered for the first time, as it will have no effect on subsequent
  * renderings of the parent tree.
  *
- * @param $element
+ * @param array $element
  *   The element to be hidden.
  *
- * @return
+ * @return array
  *   The element.
  *
  * @see render()
@@ -5919,10 +5921,10 @@ function hide(&$element) {
  * rendered for the first time, as it will have no effect on subsequent
  * renderings of the parent tree.
  *
- * @param $element
+ * @param array $element
  *   The element to be shown.
  *
- * @return
+ * @return array
  *   The element.
  *
  * @see render()
@@ -5939,9 +5941,9 @@ function show(&$element) {
  * @see drupal_render()
  * @see drupal_render_cache_set()
  *
- * @param $elements
+ * @param array $elements
  *   A renderable array.
- * @return
+ * @return string
  *   A markup string containing the rendered content of the element, or FALSE
  *   if no cached copy of the element is available.
  */
@@ -5971,9 +5973,9 @@ function drupal_render_cache_get($elements) {
  * @see drupal_render()
  * @see drupal_render_cache_get()
  *
- * @param $markup
+ * @param string $markup
  *   The rendered output string of $elements.
- * @param $elements
+ * @param array $elements
  *   A renderable array.
  */
 function drupal_render_cache_set(&$markup, $elements) {
@@ -6007,12 +6009,12 @@ function drupal_render_cache_set(&$markup, $elements) {
  * elements. This allows drupal_render() to add these back to the page when the
  * element is returned from cache.
  *
- * @param $elements
+ * @param array $elements
  *   The element to collect #attached from.
- * @param $return
+ * @param bool $return
  *   Whether to return the attached elements and reset the internal static.
  *
- * @return
+ * @return array
  *   The #attached array for this element and its descendants.
  */
 function drupal_render_collect_attached($elements, $return = FALSE) {
@@ -6051,18 +6053,18 @@ function drupal_render_collect_attached($elements, $return = FALSE) {
  * call this function. Executing the query and formatting results should happen
  * in a #pre_render callback.
  *
- * @param $query
+ * @param object $query
  *   A select query object as returned by db_select().
- * @param $function
+ * @param string $function
  *   The name of the function doing this caching. A _pre_render suffix will be
  *   added to this string and is also part of the cache key in
  *   drupal_render_cache_set() and drupal_render_cache_get().
- * @param $expire
+ * @param int $expire
  *   The cache expire time, passed eventually to cache_set().
- * @param $granularity
+ * @param int $granularity
  *   One or more granularity constants passed to drupal_render_cid_parts().
  *
- * @return
+ * @return array
  *   A renderable array with the following keys and values:
  *   - #query: The passed-in $query.
  *   - #pre_render: $function with a _pre_render suffix.
@@ -6085,12 +6087,12 @@ function drupal_render_cache_by_query($query, $function, $expire = CACHE_TEMPORA
 /**
  * Helper function for building cache ids.
  *
- * @param $granularity
+ * @param int $granularity
  *   One or more cache granularity constants, e.g. DRUPAL_CACHE_PER_USER to cache
  *   for each user separately or DRUPAL_CACHE_PER_PAGE | DRUPAL_CACHE_PER_ROLE to
  *   cache separately for each page and role.
  *
- * @return
+ * @return array
  *   An array of cache ID parts, always containing the active theme. If the
  *   locale module is enabled it also contains the active language. If
  *   $granularity was passed in, more parts are added.
@@ -6133,10 +6135,10 @@ function drupal_render_cid_parts($granularity = NULL) {
  * property if present or by building the cache ID out of the #cache['keys']
  * and, optionally, the #cache['granularity'] properties.
  *
- * @param $elements
+ * @param array $elements
  *   A renderable array.
  *
- * @return
+ * @return string|false
  *   The cache ID string, or FALSE if the element may not be cached.
  */
 function drupal_render_cid_create($elements) {
@@ -6176,7 +6178,7 @@ function element_sort_by_title($a, $b) {
 /**
  * Retrieve the default properties for the defined element type.
  *
- * @param $type
+ * @param string $type
  *   An element type as defined by hook_element_info().
  */
 function element_info($type) {
@@ -6202,11 +6204,11 @@ function element_info($type) {
 /**
  * Retrieve a single property for the defined element type.
  *
- * @param $type
+ * @param string $type
  *   An element type as defined by hook_element_info().
- * @param $property_name
+ * @param string $property_name
  *   The property within the element type that should be returned.
- * @param $default
+ * @param bool $default
  *   (Optional) The value to return if the element type does not specify a
  *   value for the property. Defaults to NULL.
  */
@@ -6266,11 +6268,11 @@ function element_child($key) {
  * The children of a element array are those key/value pairs whose key does
  * not start with a '#'. See drupal_render() for details.
  *
- * @param $elements
+ * @param array $elements
  *   The element array whose children are to be identified.
- * @param $sort
+ * @param bool $sort
  *   Boolean to indicate whether the children should be sorted by weight.
- * @return
+ * @return array
  *   The array keys of the element's children.
  */
 function element_children(&$elements, $sort = FALSE) {
@@ -6314,9 +6316,9 @@ function element_children(&$elements, $sort = FALSE) {
 /**
  * Returns the visible children of an element.
  *
- * @param $elements
+ * @param array $elements
  *   The parent element.
- * @return
+ * @return array
  *   The array keys of the element's visible children.
  */
 function element_get_visible_children(array $elements) {
@@ -6344,9 +6346,9 @@ function element_get_visible_children(array $elements) {
 /**
  * Sets HTML attributes based on element properties.
  *
- * @param $element
+ * @param array $element
  *   The renderable element to process.
- * @param $map
+ * @param array $map
  *   An associative array whose keys are element property names and whose values
  *   are the HTML attribute names to set for corresponding the property; e.g.,
  *   array('#propertyname' => 'attributename'). If both names are identical
@@ -6412,13 +6414,13 @@ function element_set_attributes(array &$element, array $map) {
  * $form['signature_settings']['signature'] = $element;
  * @endcode
  *
- * @param $array
+ * @param array $array
  *   A reference to the array to modify.
- * @param $parents
+ * @param array $parents
  *   An array of parent keys, starting with the outermost key.
- * @param $value
+ * @param mixed $value
  *   The value to set.
- * @param $force
+ * @param bool $force
  *   (Optional) If TRUE, the value is forced into the structure even if it
  *   requires the deletion of an already existing non-array parent value. If
  *   FALSE, PHP throws an error if trying to add into a value that is not an
@@ -6477,15 +6479,15 @@ function drupal_array_set_nested_value(array &$array, array $parents, $value, $f
  * $value = $form['signature_settings']['signature'];
  * @endcode
  *
- * @param $array
+ * @param array $array
  *   The array from which to get the value.
- * @param $parents
+ * @param array $parents
  *   An array of parent keys of the value, starting with the outermost key.
- * @param $key_exists
+ * @param ??? $key_exists    <== variable type??
  *   (optional) If given, an already defined variable that is altered by
  *   reference.
  *
- * @return
+ * @return mixed
  *   The requested nested value. Possibly NULL if the value is NULL or not all
  *   nested parent keys exist. $key_exists is altered by reference and is a
  *   Boolean that indicates whether all nested parent keys exist (TRUE) or not
@@ -6528,12 +6530,12 @@ function &drupal_array_get_nested_value(array &$array, array $parents, &$key_exi
  * $key_exists = array_key_exists('signature', $form['signature_settings']);
  * @endcode
  *
- * @param $array
+ * @param array $array
  *   The array with the value to check for.
- * @param $parents
+ * @param array $parents
  *   An array of parent keys of the value, starting with the outermost key.
  *
- * @return
+ * @return bool
  *   TRUE if all the parent keys exist, FALSE otherwise.
  *
  * @see drupal_array_get_nested_value()
@@ -6764,7 +6766,7 @@ function drupal_common_theme() {
  * hook_schema_alter(). The module's tables will be created exactly as the
  * module defines them.
  *
- * @param $module
+ * @param string $module
  *   The module for which the tables will be created.
  */
 function drupal_install_schema($module) {
@@ -6783,9 +6785,9 @@ function drupal_install_schema($module) {
  * hook_schema_alter(). The module's tables will be created exactly as the
  * module defines them.
  *
- * @param $module
+ * @param string $module
  *   The module for which the tables will be removed.
- * @return
+ * @return array
  *   An array of arrays with the following key/value pairs:
  *    - success: a boolean indicating whether the query succeeded.
  *    - query: the SQL query(s) executed, passed through check_plain().
@@ -6819,9 +6821,9 @@ function drupal_uninstall_schema($module) {
  * created exactly as specified without any changes introduced by a
  * module that implements hook_schema_alter().
  *
- * @param $module
+ * @param string $module
  *   The module to which the table belongs.
- * @param $table
+ * @param string|null $table
  *   The name of the table. If not given, the module's complete schema
  *   is returned.
  */
@@ -6842,12 +6844,12 @@ function drupal_get_schema_unprocessed($module, $table = NULL) {
 /**
  * Fill in required default values for table definitions returned by hook_schema().
  *
- * @param $schema
+ * @param array $schema
  *   The schema definition array as it was returned by the module's
  *   hook_schema().
- * @param $module
+ * @param string $module
  *   The module for which hook_schema() was invoked.
- * @param $remove_descriptions
+ * @param bool $remove_descriptions
  *   (optional) Whether to additionally remove 'description' keys of all tables
  *   and fields to improve performance of serialize() and unserialize().
  *   Defaults to TRUE.
@@ -6873,12 +6875,12 @@ function _drupal_schema_initialize(&$schema, $module, $remove_descriptions = TRU
 /**
  * Retrieve a list of fields from a table schema. The list is suitable for use in a SQL query.
  *
- * @param $table
+ * @param string $table
  *   The name of the table from which to retrieve fields.
- * @param
+ * @param string $prefix
  *   An optional prefix to to all fields.
  *
- * @return An array of fields.
+ * @returns array
  **/
 function drupal_schema_fields_sql($table, $prefix = NULL) {
   $schema = drupal_get_schema($table);
@@ -6898,23 +6900,23 @@ function drupal_schema_fields_sql($table, $prefix = NULL) {
 /**
  * Saves (inserts or updates) a record to the database based upon the schema.
  *
- * @param $table
+ * @param string $table
  *   The name of the table; this must be defined by a hook_schema()
  *   implementation.
- * @param $record
+ * @param object|array $record
  *   An object or array representing the record to write, passed in by
  *   reference. If inserting a new record, values not provided in $record will
  *   be populated in $record and in the database with the default values from
  *   the schema, as well as a single serial (auto-increment) field (if present).
  *   If updating an existing record, only provided values are updated in the
  *   database, and $record is not modified.
- * @param $primary_keys
+ * @param mixed $primary_keys
  *   To indicate that this is a new record to be inserted, omit this argument.
  *   If this is an update, this argument specifies the primary keys' field
  *   names. If there is only 1 field in the key, you may pass in a string; if
  *   there are multiple fields in the key, pass in an array.
  *
- * @return
+ * @return int|false
  *   If the record insert or update failed, returns FALSE. If it succeeded,
  *   returns SAVED_NEW or SAVED_UPDATED, depending on the operation performed.
  */
@@ -7083,10 +7085,10 @@ function drupal_write_record($table, &$record, $primary_keys = array()) {
  *
  * See bartik.info for an example of a theme .info file.
  *
- * @param $filename
+ * @param string $filename
  *   The file we are parsing. Accepts file with relative or absolute path.
  *
- * @return
+ * @return array
  *   The info array.
  *
  * @see drupal_parse_info_format()
@@ -7135,9 +7137,9 @@ function drupal_parse_info_file($filename) {
  * PHP constants are substituted in, but only when used as the entire value.
  * Comments should start with a semi-colon at the beginning of a line.
  *
- * @param $data
+ * @param string $data
  *   A string to parse.
- * @return
+ * @return array
  *   The info array.
  *
  * @see drupal_parse_info_file()
@@ -7202,7 +7204,7 @@ function drupal_parse_info_format($data) {
 /**
  * Severity levels, as defined in RFC 3164: http://www.ietf.org/rfc/rfc3164.txt.
  *
- * @return
+ * @return array
  *   Array of the possible severity levels for log messages.
  *
  * @see watchdog()
@@ -7324,11 +7326,11 @@ function _drupal_flush_css_js() {
  * The debug information is passed on to trigger_error() after being converted
  * to a string using _drupal_debug_message().
  *
- * @param $data
+ * @param mixed $data
  *   Data to be output.
- * @param $label
+ * @param string $label
  *   Label to prefix the data.
- * @param $print_r
+ * @param bool $print_r
  *   Flag to switch between print_r() and var_export() for data conversion to
  *   string. Set $print_r to TRUE when dealing with a recursive data structure
  *   as var_export() will generate an error.
@@ -7346,9 +7348,9 @@ function debug($data, $label = NULL, $print_r = FALSE) {
 /**
  * Parse a dependency for comparison by drupal_check_incompatibility().
  *
- * @param $dependency
+ * @param string $dependency
  *   A dependency string, for example 'foo (>=8.x-4.5-beta5, 3.x)'.
- * @return
+ * @return array
  *   An associative array with three keys:
  *   - 'name' includes the name of the thing to depend on (e.g. 'foo').
  *   - 'original_version' contains the original version string (which can be
@@ -7403,11 +7405,11 @@ function drupal_parse_dependency($dependency) {
 /**
  * Check whether a version is compatible with a given dependency.
  *
- * @param $v
+ * @param array $v
  *   The parsed dependency structure from drupal_parse_dependency().
- * @param $current_version
+ * @param array $current_version
  *   The version to check against (like 4.2).
- * @return
+ * @return string|null
  *   NULL if compatible, otherwise the original dependency version string that
  *   caused the incompatibility.
  *
@@ -7433,16 +7435,16 @@ function drupal_check_incompatibility($v, $current_version) {
  * ));
  * @endcode
  *
- * @param $url
+ * @param string $url
  *   An absolute URL of the XML-RPC endpoint.
- * @param $args
+ * @param array $args
  *   An associative array whose keys are the methods to call and whose values
  *   are the arguments to pass to the respective method. If multiple methods
  *   are specified, a system.multicall is performed.
- * @param $options
+ * @param array $options
  *   (optional) An array of options to pass along to drupal_http_request().
  *
- * @return
+ * @return ???   <== variable type??
  *   For one request:
  *     Either the return value of the method on success, or FALSE.
  *     If FALSE is returned, see xmlrpc_errno() and xmlrpc_error_msg().
@@ -7485,7 +7487,7 @@ function archiver_get_info() {
 /**
  * Returns a string of supported archive extensions.
  *
- * @return
+ * @return string
  *   A space-separated string of extensions suitable for use by the file
  *   validation system.
  */
@@ -7506,10 +7508,10 @@ function archiver_get_extensions() {
 /**
  * Create the appropriate archiver for the specified file.
  *
- * @param $file
+ * @param string $file
  *   The full path of the archive file.  Note that stream wrapper
  *   paths are supported, but not remote ones.
- * @return
+ * @return ???|false    <== variable type??
  *   A newly created instance of the archiver class appropriate
  *   for the specified file, already bound to that file.
  *   If no appropriate archiver class was found, will return FALSE.
@@ -7543,7 +7545,7 @@ function archiver_get_archiver($file) {
  * file system, for example to update modules that have newer releases, or to
  * install a new theme.
  *
- * @return
+ * @return array
  *   Returns the Drupal Updater class registry.
  *
  * @see hook_updater_info()
@@ -7562,7 +7564,7 @@ function drupal_get_updaters() {
 /**
  * Drupal FileTransfer registry.
  *
- * @return
+ * @return array
  *   Returns the Drupal FileTransfer class registry.
  *
  * @see FileTransfer
-- 
1.7.6.msysgit.0