diff options
| -rw-r--r-- | includes/password.inc | 2 | ||||
| -rw-r--r-- | includes/path.inc | 12 | ||||
| -rw-r--r-- | includes/session.inc | 2 | ||||
| -rw-r--r-- | includes/tablesort.inc | 16 | ||||
| -rw-r--r-- | includes/theme.inc | 149 | ||||
| -rw-r--r-- | includes/theme.maintenance.inc | 10 | ||||
| -rw-r--r-- | includes/token.inc | 12 | ||||
| -rw-r--r-- | includes/unicode.inc | 135 | ||||
| -rw-r--r-- | includes/update.inc | 12 | ||||
| -rw-r--r-- | includes/utility.inc | 1 |
10 files changed, 224 insertions, 127 deletions
diff --git a/includes/password.inc b/includes/password.inc index d4f5f738a..3d5a400d2 100644 --- a/includes/password.inc +++ b/includes/password.inc @@ -43,7 +43,7 @@ function _password_itoa64() { } /** - * Encode bytes into printable base 64 using the *nix standard from crypt(). + * Encodes bytes into printable base 64 using the *nix standard from crypt(). * * @param $input * The string containing bytes to encode. diff --git a/includes/path.inc b/includes/path.inc index 411a7a71c..234430ea1 100644 --- a/includes/path.inc +++ b/includes/path.inc @@ -386,7 +386,7 @@ function drupal_path_alias_whitelist_rebuild($source = NULL) { } /** - * Fetch a specific URL alias from the database. + * Fetches a specific URL alias from the database. * * @param $conditions * A string representing the source, a number representing the pid, or an @@ -475,11 +475,11 @@ function path_delete($criteria) { } /** - * Determine whether a path is in the administrative section of the site. + * Determines whether a path is in the administrative section of the site. * - * By default, paths are considered to be non-administrative. If a path does not - * match any of the patterns in path_get_admin_paths(), or if it matches both - * administrative and non-administrative patterns, it is considered + * By default, paths are considered to be non-administrative. If a path does + * not match any of the patterns in path_get_admin_paths(), or if it matches + * both administrative and non-administrative patterns, it is considered * non-administrative. * * @param $path @@ -503,7 +503,7 @@ function path_is_admin($path) { } /** - * Get a list of administrative and non-administrative paths. + * Gets a list of administrative and non-administrative paths. * * @return array * An associative array containing the following keys: diff --git a/includes/session.inc b/includes/session.inc index b04c18eb3..16727df6d 100644 --- a/includes/session.inc +++ b/includes/session.inc @@ -274,7 +274,7 @@ function drupal_session_initialize() { } /** - * Forcefully starts a session, preserving already set session data. + * Starts a session forcefully, preserving already set session data. * * @ingroup php_wrappers */ diff --git a/includes/tablesort.inc b/includes/tablesort.inc index 121a1b909..e589526c6 100644 --- a/includes/tablesort.inc +++ b/includes/tablesort.inc @@ -55,7 +55,7 @@ class TableSort extends SelectQueryExtender { } /** - * Initialize the table sort context. + * Initializes the table sort context. */ protected function init() { $ts = $this->order(); @@ -115,7 +115,7 @@ function tablesort_init($header) { } /** - * Format a column header. + * Formats a column header. * * If the cell in question is the column header for the current sort criterion, * it gets special formatting. All possible sort criteria become links. @@ -126,6 +126,7 @@ function tablesort_init($header) { * An array of column headers in the format described in theme_table(). * @param $ts * The current table sort context as returned from tablesort_init(). + * * @return * A properly formatted cell, ready for _theme_table_cell(). */ @@ -151,7 +152,7 @@ function tablesort_header($cell, $header, $ts) { } /** - * Format a table cell. + * Formats a table cell. * * Adds a class attribute to all cells in the currently active column. * @@ -163,6 +164,7 @@ function tablesort_header($cell, $header, $ts) { * The current table sort context as returned from tablesort_init(). * @param $i * The index of the cell's table column. + * * @return * A properly formatted cell, ready for _theme_table_cell(). */ @@ -179,7 +181,7 @@ function tablesort_cell($cell, $header, $ts, $i) { } /** - * Compose a URL query parameter array for table sorting links. + * Composes a URL query parameter array for table sorting links. * * @return * A URL query parameter array that consists of all components of the current @@ -190,10 +192,11 @@ function tablesort_get_query_parameters() { } /** - * Determine the current sort criterion. + * Determines the current sort criterion. * * @param $headers * An array of column headers in the format described in theme_table(). + * * @return * An associative array describing the criterion, containing the keys: * - "name": The localized title of the table column. @@ -226,10 +229,11 @@ function tablesort_get_order($headers) { } /** - * Determine the current sort direction. + * Determines the current sort direction. * * @param $headers * An array of column headers in the format described in theme_table(). + * * @return * The current sort direction ("asc" or "desc"). */ diff --git a/includes/theme.inc b/includes/theme.inc index 777922f05..4c454ba40 100644 --- a/includes/theme.inc +++ b/includes/theme.inc @@ -65,7 +65,7 @@ function _drupal_theme_access($theme) { } /** - * Initialize the theme system by loading the theme. + * Initializes the theme system by loading the theme. */ function drupal_theme_initialize() { global $theme, $user, $theme_key; @@ -113,8 +113,9 @@ function drupal_theme_initialize() { } /** - * Initialize the theme system given already loaded information. This - * function is useful to initialize a theme when no database is present. + * Initializes the theme system given already loaded information. + * + * This function is useful to initialize a theme when no database is present. * * @param $theme * An object with the following information: @@ -235,7 +236,7 @@ function _drupal_theme_initialize($theme, $base_theme = array(), $registry_callb } /** - * Get the theme registry. + * Gets the theme registry. * * @param $complete * Optional boolean to indicate whether to return the complete theme registry @@ -280,7 +281,7 @@ function theme_get_registry($complete = TRUE) { } /** - * Set the callback that will be used by theme_get_registry() to fetch the registry. + * Sets the callback that will be used by theme_get_registry(). * * @param $callback * The name of the callback function. @@ -296,7 +297,7 @@ function _theme_registry_callback($callback = NULL, array $arguments = array()) } /** - * Get the theme_registry cache; if it doesn't exist, build it. + * Gets the theme_registry cache; if it doesn't exist, builds it. * * @param $theme * The loaded $theme object as returned by list_themes(). @@ -336,16 +337,17 @@ function _theme_load_registry($theme, $base_theme = NULL, $theme_engine = NULL, } /** - * Write the theme_registry cache into the database. + * Writes the theme_registry cache into the database. */ function _theme_save_registry($theme, $registry) { cache_set("theme_registry:$theme->name", $registry); } /** - * Force the system to rebuild the theme registry; this should be called - * when modules are added to the system, or when a dynamic system needs - * to add more theme hooks. + * Forces the system to rebuild the theme registry. + * + * This function should be called when modules are added to the system, or when + * a dynamic system needs to add more theme hooks. */ function drupal_theme_rebuild() { drupal_static_reset('theme_get_registry'); @@ -635,7 +637,8 @@ function _theme_process_registry(&$cache, $name, $type, $theme, $path) { $cache = $result + $cache; } - // Let themes have variable processors even if they didn't register a template. + // Let themes have variable processors even if they didn't register a + // template. if ($type == 'theme' || $type == 'base_theme') { foreach ($cache as $hook => $info) { // Check only if not registered by the theme or engine. @@ -662,7 +665,7 @@ function _theme_process_registry(&$cache, $name, $type, $theme, $path) { } /** - * Build the theme registry cache. + * Builds the theme registry cache. * * @param $theme * The loaded $theme object as returned by list_themes(). @@ -724,7 +727,7 @@ function _theme_build_registry($theme, $base_theme, $theme_engine) { } /** - * Return a list of all currently available themes. + * Returns a list of all currently available themes. * * Retrieved from the database, if available and the site is not in maintenance * mode; otherwise compiled freshly from the filesystem. @@ -900,15 +903,15 @@ function drupal_find_base_themes($themes, $key, $used_keys = array()) { * executed (if they exist), in the following order (note that in the following * list, HOOK indicates the theme hook name, MODULE indicates a module name, * THEME indicates a theme name, and ENGINE indicates a theme engine name): - * - template_preprocess(&$variables, $hook): Creates a default set of variables - * for all theme hooks with template implementations. + * - template_preprocess(&$variables, $hook): Creates a default set of + * variables for all theme hooks with template implementations. * - template_preprocess_HOOK(&$variables): Should be implemented by the module * that registers the theme hook, to set up default variables. * - MODULE_preprocess(&$variables, $hook): hook_preprocess() is invoked on all * implementing modules. * - MODULE_preprocess_HOOK(&$variables): hook_preprocess_HOOK() is invoked on - * all implementing modules, so that modules that didn't define the theme hook - * can alter the variables. + * all implementing modules, so that modules that didn't define the theme + * hook can alter the variables. * - ENGINE_engine_preprocess(&$variables, $hook): Allows the theme engine to * set necessary variables for all theme hooks with template implementations. * - ENGINE_engine_preprocess_HOOK(&$variables): Allows the theme engine to set @@ -963,10 +966,10 @@ function drupal_find_base_themes($themes, $key, $used_keys = array()) { * @param $hook * The name of the theme hook to call. If the name contains a * double-underscore ('__') and there isn't an implementation for the full - * name, the part before the '__' is checked. This allows a fallback to a more - * generic implementation. For example, if theme('links__node', ...) is - * called, but there is no implementation of that theme hook, then the 'links' - * implementation is used. This process is iterative, so if + * name, the part before the '__' is checked. This allows a fallback to a + * more generic implementation. For example, if theme('links__node', ...) is + * called, but there is no implementation of that theme hook, then the + * 'links' implementation is used. This process is iterative, so if * theme('links__contextual__node', ...) is called, theme() checks for the * following implementations, and uses the first one that exists: * - links__contextual__node @@ -1042,7 +1045,8 @@ function theme($hook, $variables = array()) { // point path_to_theme() to the currently used theme path: $theme_path = $info['theme path']; - // Include a file if the theme function or variable processor is held elsewhere. + // Include a file if the theme function or variable processor is held + // elsewhere. if (!empty($info['includes'])) { foreach ($info['includes'] as $include_file) { include_once DRUPAL_ROOT . '/' . $include_file; @@ -1191,14 +1195,14 @@ function theme($hook, $variables = array()) { } /** - * Return the path to the current themed element. - * - * It can point to the active theme or the module handling a themed implementation. - * For example, when invoked within the scope of a theming call it will depend - * on where the theming function is handled. If implemented from a module, it - * will point to the module. If implemented from the active theme, it will point - * to the active theme. When called outside the scope of a theming call, it will - * always point to the active theme. + * Returns the path to the current themed element. + * + * It can point to the active theme or the module handling a themed + * implementation. For example, when invoked within the scope of a theming call + * it will depend on where the theming function is handled. If implemented from + * a module, it will point to the module. If implemented from the active theme, + * it will point to the active theme. When called outside the scope of a + * theming call, it will always point to the active theme. */ function path_to_theme() { global $theme_path; @@ -1211,7 +1215,7 @@ function path_to_theme() { } /** - * Allow themes and/or theme engines to easily discover overridden theme functions. + * Allows themes and/or theme engines to discover overridden theme functions. * * @param $cache * The existing cache of theme hooks to test against. @@ -1268,7 +1272,7 @@ function drupal_find_theme_functions($cache, $prefixes) { } /** - * Allow themes and/or theme engines to easily discover overridden templates. + * Allows themes and/or theme engines to easily discover overridden templates. * * @param $cache * The existing cache of theme hooks to test against. @@ -1345,7 +1349,8 @@ function drupal_find_theme_templates($cache, $extension, $path) { if ($matches) { foreach ($matches as $match) { $file = substr($match, 0, strpos($match, '.')); - // Put the underscores back in for the hook name and register this pattern. + // Put the underscores back in for the hook name and register this + // pattern. $arg_name = isset($info['variables']) ? 'variables' : 'render element'; $implementations[strtr($file, '-', '_')] = array( 'template' => $file, @@ -1361,7 +1366,7 @@ function drupal_find_theme_templates($cache, $extension, $path) { } /** - * Retrieve a setting for the current theme or for a given theme. + * Retrieves a setting for the current theme or for a given theme. * * The final setting is obtained from the last value found in the following * sources: @@ -1479,7 +1484,7 @@ function theme_get_setting($setting_name, $theme = NULL) { } /** - * Render a system default template, which is essentially a PHP template. + * Renders a system default template, which is essentially a PHP template. * * @param $template_file * The filename of the template to render. @@ -1490,14 +1495,21 @@ function theme_get_setting($setting_name, $theme = NULL) { * The output generated by the template. */ function theme_render_template($template_file, $variables) { - extract($variables, EXTR_SKIP); // Extract the variables to a local namespace - ob_start(); // Start output buffering - include DRUPAL_ROOT . '/' . $template_file; // Include the template file - return ob_get_clean(); // End buffering and return its contents + // Extract the variables to a local namespace + extract($variables, EXTR_SKIP); + + // Start output buffering + ob_start(); + + // Include the template file + include DRUPAL_ROOT . '/' . $template_file; + + // End buffering and return its contents + return ob_get_clean(); } /** - * Enable a given list of themes. + * Enables a given list of themes. * * @param $theme_list * An array of theme names. @@ -1522,7 +1534,7 @@ function theme_enable($theme_list) { } /** - * Disable a given list of themes. + * Disables a given list of themes. * * @param $theme_list * An array of theme names. @@ -1608,13 +1620,13 @@ function theme_status_messages($variables) { * theme('link') for rendering the anchor tag. * * To optimize performance for sites that don't need custom theming of links, - * the l() function includes an inline copy of this function, and uses that copy - * if none of the enabled modules or the active theme implement any preprocess - * or process functions or override this theme implementation. + * the l() function includes an inline copy of this function, and uses that + * copy if none of the enabled modules or the active theme implement any + * preprocess or process functions or override this theme implementation. * * @param $variables - * An associative array containing the keys 'text', 'path', and 'options'. See - * the l() function for information about these variables. + * An associative array containing the keys 'text', 'path', and 'options'. + * See the l() function for information about these variables. * * @see l() */ @@ -1635,15 +1647,16 @@ function theme_link($variables) { * item in the links list. * - html: (optional) Whether or not 'title' is HTML. If set, the title * will not be passed through check_plain(). - * - attributes: (optional) Attributes for the anchor, or for the <span> tag - * used in its place if no 'href' is supplied. If element 'class' is + * - attributes: (optional) Attributes for the anchor, or for the <span> + * tag used in its place if no 'href' is supplied. If element 'class' is * included, it must be an array of one or more class names. - * If the 'href' element is supplied, the entire link array is passed to l() - * as its $options parameter. + * If the 'href' element is supplied, the entire link array is passed to + * l() as its $options parameter. * - attributes: A keyed array of attributes for the UL containing the * list of links. - * - heading: (optional) A heading to precede the links. May be an associative - * array or a string. If it's an array, it can have the following elements: + * - heading: (optional) A heading to precede the links. May be an + * associative array or a string. If it's an array, it can have the + * following elements: * - text: The heading text. * - level: The heading level (e.g. 'h2', 'h3'). * - class: (optional) An array of the CSS classes for the heading. @@ -1747,8 +1760,8 @@ function theme_links($variables) { * attribute to be omitted in some cases. Therefore, this variable defaults * to an empty string, but can be set to NULL for the attribute to be * omitted. Usually, neither omission nor an empty string satisfies - * accessibility requirements, so it is strongly encouraged for code calling - * theme('image') to pass a meaningful value for this variable. + * accessibility requirements, so it is strongly encouraged for code + * calling theme('image') to pass a meaningful value for this variable. * - http://www.w3.org/TR/REC-html40/struct/objects.html#h-13.8 * - http://www.w3.org/TR/xhtml1/dtds.html * - http://dev.w3.org/html5/spec/Overview.html#alt @@ -2005,7 +2018,8 @@ function theme_table($variables) { * * @param $variables * An associative array containing: - * - style: Set to either 'asc' or 'desc', this determines which icon to show. + * - style: Set to either 'asc' or 'desc', this determines which icon to + * show. */ function theme_tablesort_indicator($variables) { if ($variables['style'] == "asc") { @@ -2148,7 +2162,8 @@ function theme_feed_icon($variables) { * - script: To load JavaScript. * - #attributes: (optional) An array of HTML attributes to apply to the * tag. - * - #value: (optional) A string containing tag content, such as inline CSS. + * - #value: (optional) A string containing tag content, such as inline + * CSS. * - #value_prefix: (optional) A string to prepend to #value, e.g. a CDATA * wrapper prefix. * - #value_suffix: (optional) A string to append to #value, e.g. a CDATA @@ -2316,8 +2331,9 @@ function template_preprocess(&$variables, $hook) { global $user; static $count = array(); - // Track run count for each hook to provide zebra striping. - // See "template_preprocess_block()" which provides the same feature specific to blocks. + // Track run count for each hook to provide zebra striping. See + // "template_preprocess_block()" which provides the same feature specific to + // blocks. $count[$hook] = isset($count[$hook]) && is_int($count[$hook]) ? $count[$hook] : 1; $variables['zebra'] = ($count[$hook] % 2) ? 'odd' : 'even'; $variables['id'] = $count[$hook]++; @@ -2677,13 +2693,13 @@ function theme_get_suggestions($args, $base, $delimiter = '__') { } /** - * The variables array generated here is a mirror of template_preprocess_page(). - * This preprocessor will run its course when theme_maintenance_page() is - * invoked. + * Process variables for maintenance-page.tpl.php. * - * An alternate template file of "maintenance-page--offline.tpl.php" can be - * used when the database is offline to hide errors and completely replace the - * content. + * The variables array generated here is a mirror of + * template_preprocess_page(). This preprocessor will run its course when + * theme_maintenance_page() is invoked. An alternate template file of + * maintenance-page--offline.tpl.php can be used when the database is offline to + * hide errors and completely replace the content. * * The $variables array contains the following arguments: * - $content @@ -2777,10 +2793,13 @@ function template_preprocess_maintenance_page(&$variables) { } /** + * Theme process function for theme_maintenance_field(). + * * The variables array generated here is a mirror of template_process_html(). * This processor will run its course when theme_maintenance_page() is invoked. * * @see maintenance-page.tpl.php + * @see template_process_html() */ function template_process_maintenance_page(&$variables) { $variables['head'] = drupal_get_html_head(); @@ -2792,7 +2811,7 @@ function template_process_maintenance_page(&$variables) { /** * Preprocess variables for region.tpl.php * - * Prepare the values passed to the theme_region function to be passed into a + * Prepares the values passed to the theme_region function to be passed into a * pluggable template engine. Uses the region name to generate a template file * suggestions. If none are found, the default region.tpl.php is used. * diff --git a/includes/theme.maintenance.inc b/includes/theme.maintenance.inc index 218a8adaa..6baf219b0 100644 --- a/includes/theme.maintenance.inc +++ b/includes/theme.maintenance.inc @@ -10,9 +10,9 @@ * * Used for site installs, updates and when the site is in maintenance mode. * It also applies when the database is unavailable or bootstrap was not - * complete. Seven is always used for the initial install and update operations. - * In other cases, Bartik is used, but this can be overridden by setting a - * "maintenance_theme" key in the $conf variable in settings.php. + * complete. Seven is always used for the initial install and update + * operations. In other cases, Bartik is used, but this can be overridden by + * setting a "maintenance_theme" key in the $conf variable in settings.php. */ function _drupal_maintenance_theme() { global $theme, $theme_key, $conf; @@ -85,7 +85,7 @@ function _drupal_maintenance_theme() { } /** - * This builds the registry when the site needs to bypass any database calls. + * Builds the registry when the site needs to bypass any database calls. */ function _theme_load_offline_registry($theme, $base_theme = NULL, $theme_engine = NULL) { return _theme_build_registry($theme, $base_theme, $theme_engine); @@ -160,7 +160,7 @@ function theme_update_page($variables) { } /** - * Returns HTML for a report of the results from an operation run via authorize.php. + * Returns HTML for a results report of an operation run by authorize.php. * * @param $variables * An associative array containing: diff --git a/includes/token.inc b/includes/token.inc index 0b05c68f4..402aeae01 100644 --- a/includes/token.inc +++ b/includes/token.inc @@ -190,10 +190,10 @@ function token_generate($type, array $tokens, array $data = array(), array $opti } /** - * Given a list of tokens, returns those that begin with a specific prefix. + * Returns a list of tokens that begin with a specific prefix. * - * Used to extract a group of 'chained' tokens (such as [node:author:name]) from - * the full list of tokens found in text. For example: + * Used to extract a group of 'chained' tokens (such as [node:author:name]) + * from the full list of tokens found in text. For example: * @code * $data = array( * 'author:name' => '[node:author:name]', @@ -230,8 +230,10 @@ function token_find_with_prefix(array $tokens, $prefix, $delimiter = ':') { /** * Returns metadata describing supported tokens. * - * The metadata array contains token type, name, and description data as well as - * an optional pointer indicating that the token chains to another set of tokens. + * The metadata array contains token type, name, and description data as well + * as an optional pointer indicating that the token chains to another set of + * tokens. + * * For example: * @code * $data['types']['node'] = array( diff --git a/includes/unicode.inc b/includes/unicode.inc index 81a0a4dfe..fd497cca7 100644 --- a/includes/unicode.inc +++ b/includes/unicode.inc @@ -1,6 +1,11 @@ <?php /** +* @file +* Provides Unicode-related conversions and operations. +*/ + +/** * Indicates an error during check for PHP unicode support. */ define('UNICODE_ERROR', -1); @@ -19,8 +24,6 @@ define('UNICODE_MULTIBYTE', 1); /** * Matches Unicode characters that are word boundaries. * - * @see http://unicode.org/glossary - * * Characters with the following General_category (gc) property values are used * as word boundaries. While this does not fully conform to the Word Boundaries * algorithm described in http://unicode.org/reports/tr29, as PCRE does not @@ -39,6 +42,8 @@ define('UNICODE_MULTIBYTE', 1); * Note that the PCRE property matcher is not used because we wanted to be * compatible with Unicode 5.2.0 regardless of the PCRE version used (and any * bugs in PCRE property tables). + * + * @see http://unicode.org/glossary */ define('PREG_CLASS_UNICODE_WORD_BOUNDARY', '\x{0}-\x{2F}\x{3A}-\x{40}\x{5B}-\x{60}\x{7B}-\x{A9}\x{AB}-\x{B1}\x{B4}' . @@ -125,7 +130,7 @@ function _unicode_check() { } /** - * Return Unicode library status and errors. + * Returns Unicode library status and errors. */ function unicode_requirements() { // Ensure translations don't break during installation. @@ -157,14 +162,14 @@ function unicode_requirements() { } /** - * Prepare a new XML parser. + * Prepares a new XML parser. * - * This is a wrapper around xml_parser_create() which extracts the encoding from - * the XML data first and sets the output encoding to UTF-8. This function should - * be used instead of xml_parser_create(), because PHP 4's XML parser doesn't - * check the input encoding itself. "Starting from PHP 5, the input encoding is - * automatically detected, so that the encoding parameter specifies only the - * output encoding." + * This is a wrapper around xml_parser_create() which extracts the encoding + * from the XML data first and sets the output encoding to UTF-8. This function + * should be used instead of xml_parser_create(), because PHP 4's XML parser + * doesn't check the input encoding itself. "Starting from PHP 5, the input + * encoding is automatically detected, so that the encoding parameter specifies + * only the output encoding." * * This is also where unsupported encodings will be converted. Callers should * take this into account: $data might have been changed after the call. @@ -213,7 +218,7 @@ function drupal_xml_parser_create(&$data) { } /** - * Convert data to UTF-8 + * Converts data to UTF-8. * * Requires the iconv, GNU recode or mbstring PHP extension. * @@ -244,15 +249,15 @@ function drupal_convert_to_utf8($data, $encoding) { } /** - * Truncate a UTF-8-encoded string safely to a number of bytes. + * Truncates a UTF-8-encoded string safely to a number of bytes. * * If the end position is in the middle of a UTF-8 sequence, it scans backwards * until the beginning of the byte sequence. * * Use this function whenever you want to chop off a string at an unsure * location. On the other hand, if you're sure that you're splitting on a - * character boundary (e.g. after using strpos() or similar), you can safely use - * substr() instead. + * character boundary (e.g. after using strpos() or similar), you can safely + * use substr() instead. * * @param $string * The string to truncate. @@ -306,7 +311,7 @@ function drupal_truncate_bytes($string, $len) { * boundaries, giving you "See myverylongurl..." (assuming you had set * $add_ellipses to TRUE). * - * @return + * @return string * The truncated string. */ function truncate_utf8($string, $max_length, $wordsafe = FALSE, $add_ellipsis = FALSE, $min_wordsafe_length = 1) { @@ -356,8 +361,7 @@ function truncate_utf8($string, $max_length, $wordsafe = FALSE, $add_ellipsis = } /** - * Encodes MIME/HTTP header values that contain non-ASCII, UTF-8 encoded - * characters. + * Encodes MIME/HTTP header values that contain incorrectly encoded characters. * * For example, mime_header_encode('tést.txt') returns "=?UTF-8?B?dMOpc3QudHh0?=". * @@ -369,6 +373,14 @@ function truncate_utf8($string, $max_length, $wordsafe = FALSE, $add_ellipsis = * each chunk starts and ends on a character boundary. * - Using \n as the chunk separator may cause problems on some systems and may * have to be changed to \r\n or \r. + * + * @param $string + * The header to encode. + * + * @return string + * The mime-encoded header. + * + * @see mime_header_decode() */ function mime_header_encode($string) { if (preg_match('/[^\x20-\x7E]/', $string)) { @@ -388,7 +400,15 @@ function mime_header_encode($string) { } /** - * Complement to mime_header_encode + * Decodes MIME/HTTP encoded header values. + * + * @param $header + * The header to decode. + * + * @return string + * The mime-decoded header. + * + * @see mime_header_encode() */ function mime_header_decode($header) { // First step: encoded chunks followed by other encoded chunks (need to collapse whitespace) @@ -398,7 +418,17 @@ function mime_header_decode($header) { } /** - * Helper function to mime_header_decode + * Decodes encoded header data passed from mime_header_decode(). + * + * Callback for preg_replace_callback() within mime_header_decode(). + * + * @param $matches + * The array of matches from preg_replace_callback(). + * + * @return string + * The mime-decoded string. + * + * @see mime_header_decode() */ function _mime_header_decode($matches) { // Regexp groups: @@ -415,9 +445,9 @@ function _mime_header_decode($matches) { /** * Decodes all HTML entities (including numerical ones) to regular UTF-8 bytes. * - * Double-escaped entities will only be decoded once ("&lt;" becomes "<", - * not "<"). Be careful when using this function, as decode_entities can revert - * previous sanitization efforts (<script> will become <script>). + * Double-escaped entities will only be decoded once ("&lt;" becomes "<" + * , not "<"). Be careful when using this function, as decode_entities can + * revert previous sanitization efforts (<script> will become <script>). * * @param $text * The text to decode entities in. @@ -430,8 +460,15 @@ function decode_entities($text) { } /** - * Count the amount of characters in a UTF-8 string. This is less than or - * equal to the byte count. + * Counts the number of characters in a UTF-8 string. + * + * This is less than or equal to the byte count. + * + * @param $text + * The string to run the operation on. + * + * @return integer + * The length of the string. * * @ingroup php_wrappers */ @@ -449,6 +486,12 @@ function drupal_strlen($text) { /** * Uppercase a UTF-8 string. * + * @param $text + * The string to run the operation on. + * + * @return string + * The string in uppercase. + * * @ingroup php_wrappers */ function drupal_strtoupper($text) { @@ -468,6 +511,12 @@ function drupal_strtoupper($text) { /** * Lowercase a UTF-8 string. * + * @param $text + * The string to run the operation on. + * + * @return string + * The string in lowercase. + * * @ingroup php_wrappers */ function drupal_strtolower($text) { @@ -485,15 +534,28 @@ function drupal_strtolower($text) { } /** - * Helper function for case conversion of Latin-1. - * Used for flipping U+C0-U+DE to U+E0-U+FD and back. + * Flips U+C0-U+DE to U+E0-U+FD and back. + * + * @param $matches + * An array of matches. + * + * @return array + * The Latin-1 version of the array of matches. + * + * @see drupal_strtolower() */ function _unicode_caseflip($matches) { return $matches[0][0] . chr(ord($matches[0][1]) ^ 32); } /** - * Capitalize the first letter of a UTF-8 string. + * Capitalizes the first letter of a UTF-8 string. + * + * @param $text + * The string to convert. + * + * @return + * The string with the first letter as uppercase. * * @ingroup php_wrappers */ @@ -503,12 +565,21 @@ function drupal_ucfirst($text) { } /** - * Cut off a piece of a string based on character indices and counts. Follows - * the same behavior as PHP's own substr() function. + * Cuts off a piece of a string based on character indices and counts. * - * Note that for cutting off a string at a known character/substring - * location, the usage of PHP's normal strpos/substr is safe and - * much faster. + * Follows the same behavior as PHP's own substr() function. Note that for + * cutting off a string at a known character/substring location, the usage of + * PHP's normal strpos/substr is safe and much faster. + * + * @param $text + * The input string. + * @param $start + * The position at which to start reading. + * @param $length + * The number of characters to read. + * + * @return + * The shortened string. * * @ingroup php_wrappers */ diff --git a/includes/update.inc b/includes/update.inc index 5f1c2331c..a17161c9e 100644 --- a/includes/update.inc +++ b/includes/update.inc @@ -38,7 +38,7 @@ function update_fix_compatibility() { } /** - * Helper function to test compatibility of a module or theme. + * Tests the compatibility of a module or theme. */ function update_check_incompatibility($name, $type = 'module') { static $themes, $modules; @@ -908,7 +908,7 @@ function update_get_d6_session_name() { } /** - * Perform one update and store the results for display on finished page. + * Performs one update and stores the results for display on the results page. * * If an update function completes successfully, it should return a message * as a string indicating success, for example: @@ -1008,7 +1008,7 @@ function update_do_one($module, $number, $dependency_map, &$context) { class DrupalUpdateException extends Exception { } /** - * Start the database update batch process. + * Starts the database update batch process. * * @param $start * An array whose keys contain the names of modules to be updated during the @@ -1078,7 +1078,7 @@ function update_batch($start, $redirect = NULL, $url = NULL, $batch = array(), $ } /** - * Finish the update process and store results for eventual display. + * Finishes the update process and stores the results for eventual display. * * After the updates run, all caches are flushed. The update results are * stored into the session (for example, to be displayed on the update results @@ -1115,7 +1115,7 @@ function update_finished($success, $results, $operations) { } /** - * Return a list of all the pending database updates. + * Returns a list of all the pending database updates. * * @return * An associative array keyed by module name which contains all information @@ -1409,7 +1409,7 @@ function update_already_performed($module, $number) { } /** - * Invoke hook_update_dependencies() in all installed modules. + * Invokes hook_update_dependencies() in all installed modules. * * This function is similar to module_invoke_all(), with the main difference * that it does not require that a module be enabled to invoke its hook, only diff --git a/includes/utility.inc b/includes/utility.inc index 5019852c7..f651fd631 100644 --- a/includes/utility.inc +++ b/includes/utility.inc @@ -12,6 +12,7 @@ * The variable to export. * @param $prefix * A prefix that will be added at the beginning of every lines of the output. + * * @return * The variable exported in a way compatible to Drupal's coding standards. */ |