summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorJennifer Hodgdon2013-01-16 18:01:31 (GMT)
committer Jennifer Hodgdon2013-01-16 18:01:31 (GMT)
commita03edeb357816e1fa68586e1fef5be0d8f5257c3 (patch)
tree29e8856a6036f63ff07616fa650ce27d055cae9a
parentcc65ed1091ba0e7bf9e054fd8304d2a7108167d2 (diff)
Issue #1317628 by Albert Volkman, Gaelan, disasm, mjonesdinero, xjm: Clean up API docs for include files n-z
-rw-r--r--includes/password.inc2
-rw-r--r--includes/path.inc12
-rw-r--r--includes/session.inc2
-rw-r--r--includes/tablesort.inc16
-rw-r--r--includes/theme.inc149
-rw-r--r--includes/theme.maintenance.inc10
-rw-r--r--includes/token.inc12
-rw-r--r--includes/unicode.inc135
-rw-r--r--includes/update.inc12
-rw-r--r--includes/utility.inc1
10 files changed, 224 insertions, 127 deletions
diff --git a/includes/password.inc b/includes/password.inc
index d4f5f73..3d5a400 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 411a7a7..234430e 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 b04c18e..16727df 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 121a1b9..e589526 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 777922f..4c454ba 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 218a8ad..6baf219 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 0b05c68..402aeae 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 81a0a4d..fd497cc 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 ("&amp;lt;" becomes "&lt;",
- * not "<"). Be careful when using this function, as decode_entities can revert
- * previous sanitization efforts (&lt;script&gt; will become <script>).
+ * Double-escaped entities will only be decoded once ("&amp;lt;" becomes "&lt;"
+ * , not "<"). Be careful when using this function, as decode_entities can
+ * revert previous sanitization efforts (&lt;script&gt; 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 5f1c233..a17161c 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 5019852..f651fd6 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.
*/