Commit 4824c219 authored by jhodgdon's avatar jhodgdon

Issue #1317628 by Albert Volkman, Gaelan, disasm, mjonesdinero, xjm: Clean up...

Issue #1317628 by Albert Volkman, Gaelan, disasm, mjonesdinero, xjm: Clean up for API docs in include files starting with n-z
parent b5548325
......@@ -96,7 +96,7 @@ function current_path() {
}
/**
* 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
......@@ -118,11 +118,11 @@ function path_load($conditions) {
}
/**
* 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
......@@ -146,7 +146,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:
......
......@@ -123,8 +123,8 @@ function drupal_get_complete_schema($rebuild = FALSE) {
* A module name.
*
* @return array|bool
* If the module has updates, an array of available updates sorted by version.
* Otherwise, FALSE.
* If the module has updates, an array of available updates sorted by
* version. Otherwise, FALSE.
*/
function drupal_get_schema_versions($module) {
$updates = &drupal_static(__FUNCTION__, NULL);
......@@ -369,9 +369,9 @@ function drupal_schema_fields_sql($table, $prefix = NULL) {
* 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.
* 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 array $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
......
......@@ -270,7 +270,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
*/
......
......@@ -13,7 +13,7 @@
*/
/**
* Initialize the table sort context.
* Initializes the table sort context.
*/
function tablesort_init($header) {
$ts = tablesort_get_order($header);
......@@ -23,7 +23,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.
......@@ -34,6 +34,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().
*/
......@@ -63,7 +64,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.
*
......@@ -75,6 +76,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().
*/
......@@ -91,7 +93,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
......@@ -102,10 +104,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.
......@@ -138,10 +141,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").
*/
......
This diff is collapsed.
......@@ -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;
......@@ -89,7 +89,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);
......@@ -165,7 +165,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:
......
......@@ -61,10 +61,11 @@
* replacement process. Supported options are:
* - langcode: A language code to be used when generating locale-sensitive
* tokens.
* - callback: A callback function that will be used to post-process the array
* of token replacements after they are generated. For example, a module
* using tokens in a text-only email might provide a callback to strip HTML
* entities from token values before they are inserted into the final text.
* - callback: A callback function that will be used to post-process the
* array of token replacements after they are generated. For example, a
* module using tokens in a text-only email might provide a callback to
* strip HTML entities from token values before they are inserted into the
* final text.
* - clear: A boolean flag indicating that tokens should be removed from the
* final text if no replacement value can be generated.
* - sanitize: A boolean flag indicating that tokens should be sanitized for
......@@ -190,10 +191,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 +231,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(
......
<?php
/**
* @file
* Provides Unicode-related conversions and operations.
*/
/**
* 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
......@@ -23,6 +26,8 @@
* 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}' .
......@@ -62,7 +67,7 @@
'\x{FF3B}-\x{FF40}\x{FF5B}-\x{FF65}\x{FFE0}-\x{FFFD}');
/**
* Return Unicode library status and errors.
* Returns Unicode library status and errors.
*/
function unicode_requirements() {
// Ensure translations don't break during installation.
......@@ -113,14 +118,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.
......@@ -169,7 +174,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.
*
......@@ -200,15 +205,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.
......@@ -262,7 +267,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) {
......@@ -315,8 +320,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?=".
*
......@@ -328,6 +332,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)) {
......@@ -347,7 +359,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)
......@@ -357,7 +377,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:
......@@ -374,9 +404,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.
......@@ -389,8 +419,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
*/
......@@ -408,6 +445,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) {
......@@ -427,6 +470,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) {
......@@ -444,15 +493,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
*/
......@@ -462,12 +524,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.
*
* 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.
*
* 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
*/
......
......@@ -47,7 +47,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;
......@@ -418,7 +418,7 @@ function update_prepare_d8_bootstrap() {
}
/**
* Fix stored include paths to match the "/core" migration.
* Fixes stored include paths to match the "/core" migration.
*/
function update_prepare_stored_includes() {
// Update language negotiation settings.
......@@ -434,7 +434,7 @@ function update_prepare_stored_includes() {
}
/**
* Prepare Drupal 8 language changes for the bootstrap if needed.
* Prepares Drupal 8 language changes for the bootstrap if needed.
*/
function update_prepare_d8_language() {
if (db_table_exists('languages')) {
......@@ -603,8 +603,7 @@ function update_prepare_d8_language() {
}
/**
* Perform Drupal 7.x to 8.x updates that are required for update.php
* to function properly.
* Performs Drupal 7.x to 8.x required update.php updates.
*
* This function runs when update.php is run the first time for 8.x,
* even before updates are selected or performed. It is important
......@@ -625,7 +624,7 @@ function update_fix_d8_requirements() {
}
/**
* Helper function to install a new module in Drupal 8 via hook_update_N().
* Installs a new module in Drupal 8 via hook_update_N().
*/
function update_module_enable(array $modules) {
$schema_store = drupal_container()->get('keyvalue')->get('system.schema');
......@@ -664,7 +663,7 @@ function update_module_enable(array $modules) {
}
/**
* 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:
......@@ -762,7 +761,7 @@ function update_do_one($module, $number, $dependency_map, &$context) {
}
/**
* 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
......@@ -840,7 +839,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
......@@ -875,7 +874,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
......@@ -965,8 +964,8 @@ function update_get_update_list() {
* containing all the keys provided by the
* Drupal\Component\Graph\Graph::searchAndSort() algorithm, which encode
* detailed information about the dependency chain for this update function
* (for example: 'paths', 'reverse_paths', 'weight', and 'component'), as well
* as the following additional keys:
* (for example: 'paths', 'reverse_paths', 'weight', and 'component'), as
* well as the following additional keys:
* - 'allowed': A boolean which is TRUE when the update function's
* dependencies are met, and FALSE otherwise. Calling functions should
* inspect this value before running the update.
......@@ -1171,7 +1170,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
......@@ -1307,10 +1306,10 @@ function update_variable_del($name) {
}
/**
* Updates config with values set on Drupal 7.x
* Updates config with values set on Drupal 7.x.
*
* Provide a generalised method to migrate variables from Drupal 7 to Drupal 8's
* configuration management system.
* Provides a generalised method to migrate variables from Drupal 7 to
* Drupal 8's configuration management system.
*
* @param string $config_name
* The configuration object name to retrieve.
......
......@@ -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.
*/
......
......@@ -56,7 +56,7 @@ function __construct($countLog2) {
}
/**
* 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 String $input
* The string containing bytes to encode.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment