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

core/includes/path.inc

@@ -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:

core/includes/schema.inc

@@ -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

core/includes/session.inc

@@ -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
  */

core/includes/tablesort.inc

@@ -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").
  */

core/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;
@@ -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:

core/includes/token.inc

@@ -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(

core/includes/unicode.inc

 <?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
  */

core/includes/update.inc

@@ -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.

core/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.
  */

core/lib/Drupal/Core/Password/PhpassHashedPassword.php

@@ -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.