From d428fe37b91d9fb04b62d19d8ce04da32a1ac96c Mon Sep 17 00:00:00 2001 From: Dries Buytaert Date: Fri, 26 Mar 2010 17:14:46 +0000 Subject: - Patch #681538 by aspilicious, jhodgdon, trevjs: fixed possibly broken @see also links. --- includes/bootstrap.inc | 20 +++++++++++++------- includes/common.inc | 17 +++++++++-------- includes/database/prefetch.inc | 5 ++--- includes/file.inc | 17 +++++++++++------ includes/form.inc | 14 +++++++------- includes/menu.inc | 36 +++++++++++++++++++++++++++--------- includes/module.inc | 2 +- includes/registry.inc | 2 +- includes/stream_wrappers.inc | 4 ++-- includes/theme.inc | 14 +++++++------- 10 files changed, 80 insertions(+), 51 deletions(-) (limited to 'includes') diff --git a/includes/bootstrap.inc b/includes/bootstrap.inc index 15ff5af10..6deab8a79 100644 --- a/includes/bootstrap.inc +++ b/includes/bootstrap.inc @@ -752,10 +752,12 @@ function variable_initialize($conf = array()) { * The name of the variable to return. * @param $default * The default value to use if this variable has never been set. + * * @return * The value of the variable. * - * @see variable_del(), variable_set() + * @see variable_del() + * @see variable_set() */ function variable_get($name, $default = NULL) { global $conf; @@ -772,7 +774,8 @@ function variable_get($name, $default = NULL) { * The value to set. This can be any PHP data type; these functions take care * of serialization as necessary. * - * @see variable_del(), variable_get() + * @see variable_del() + * @see variable_get() */ function variable_set($name, $value) { global $conf; @@ -790,7 +793,8 @@ function variable_set($name, $value) { * @param $name * The name of the variable to undefine. * - * @see variable_get(), variable_set() + * @see variable_get() + * @see variable_set() */ function variable_del($name) { global $conf; @@ -1438,10 +1442,12 @@ function t($string, array $args = array(), array $options = array()) { * * @param $text * The text to be checked or processed. + * * @return * An HTML safe version of $text, or an empty string if $text is not * valid UTF-8. - * @see drupal_validate_utf8(). + * + * @see drupal_validate_utf8() */ function check_plain($text) { // We do not want to use drupal_static() since PHP version will never change @@ -1455,8 +1461,8 @@ function check_plain($text) { // drupal_validate_utf8() here. This avoids the overhead of an additional // function call, since check_plain() may be called hundreds of times during // a request. For PHP 5.2.5+, this check for valid UTF-8 should be handled - // internally by PHP in htmlspecialchars(). - // @see http://www.php.net/releases/5_2_5.php + // internally by PHP in htmlspecialchars(). + // See http://www.php.net/releases/5_2_5.php. // @todo remove this when support for either IE6 or PHP < 5.2.5 is dropped. if ($php525) { @@ -2539,7 +2545,7 @@ function registry_update() { * - http://php.net/manual/en/language.variables.scope.php#language.variables.scope.static * - http://php.net/manual/en/language.variables.scope.php#language.variables.scope.references * The example below shows the syntax needed to work around both limitations. - * For benchmarks and more information, @see http://drupal.org/node/619666. + * For benchmarks and more information, see http://drupal.org/node/619666. * * Example: * @code diff --git a/includes/common.inc b/includes/common.inc index e25a744d2..5857aac6d 100644 --- a/includes/common.inc +++ b/includes/common.inc @@ -818,7 +818,7 @@ function drupal_http_request($url, array $options = array()) { // Mark that this request failed. This will trigger a check of the web // server's ability to make outgoing HTTP requests the next time that // requirements checking is performed. - // @see system_requirements() + // See system_requirements() variable_set('drupal_http_request_fails', TRUE); return $result; @@ -3758,14 +3758,15 @@ function drupal_get_js($scope = 'header', $javascript = NULL) { * When TRUE, will exit if a given library's dependencies are missing. When * set to FALSE, will continue to add the libraries, even though one of the * dependencies are missing. Defaults to FALSE. + * * @return * Will return FALSE if there were any missing library dependencies. TRUE will * be returned if all library dependencies were met. * - * @see drupal_add_library(). - * @see drupal_add_js(). - * @see drupal_add_css(). - * @see drupal_render(). + * @see drupal_add_library() + * @see drupal_add_js() + * @see drupal_add_css() + * @see drupal_render() */ function drupal_process_attached($elements, $weight = JS_DEFAULT, $dependency_check = FALSE) { // Add defaults to the special attached structures that should be processed differently. @@ -4779,7 +4780,7 @@ function drupal_pre_render_markup($elements) { * - #show_messages: Suppress drupal_get_message() items. Used by Batch API (optional). * * @see hook_page_alter() - * @see element_info('page') + * @see element_info() */ function drupal_render_page($page) { $main_content_display = &drupal_static('system_main_content_added', FALSE); @@ -4845,8 +4846,8 @@ function drupal_render_page($page) { * improve performance. To use drupal_render() caching, set the element's #cache * property to an associative array with one or several of the following keys: * - 'keys': An array of one or more keys that identify the element. If 'keys' - * is set, the cache ID is created automatically from these keys. - * @see drupal_render_cid_create() + * is set, the cache ID is created automatically from these keys. See + * drupal_render_cid_create(). * - 'granularity' (optional): Define the cache granularity using binary * combinations of the cache granularity constants, e.g. DRUPAL_CACHE_PER_USER * to cache for each user separately or diff --git a/includes/database/prefetch.inc b/includes/database/prefetch.inc index 663927af7..9d02dcfc2 100644 --- a/includes/database/prefetch.inc +++ b/includes/database/prefetch.inc @@ -175,9 +175,8 @@ class DatabaseStatementPrefetch implements Iterator, DatabaseStatementInterface // as soon as possible. $this->rowCount = $statement->rowCount(); $this->data = $statement->fetchAll(PDO::FETCH_ASSOC); - // Destroy the statement as soon as possible. - // See DatabaseConnection_sqlite::PDOPrepare() for explanation. - // @see DatabaseConnection_sqlite::PDOPrepare() + // Destroy the statement as soon as possible. See + // DatabaseConnection_sqlite::PDOPrepare() for explanation. unset($statement); $this->resultRowCount = count($this->data); diff --git a/includes/file.inc b/includes/file.inc index 1b06895af..baa0a9473 100644 --- a/includes/file.inc +++ b/includes/file.inc @@ -536,8 +536,8 @@ function file_save(stdClass $file) { * - If file already exists in $destination either the call will error out, * replace the file or rename the file based on the $replace parameter. * - Adds the new file to the files database. If the source file is a - * temporary file, the resulting file will also be a temporary file. - * @see file_save_upload() for details on temporary files. + * temporary file, the resulting file will also be a temporary file. See + * file_save_upload() for details on temporary files. * * @param $source * A file object. @@ -553,6 +553,7 @@ function file_save(stdClass $file) { * - FILE_EXISTS_RENAME - Append _{incrementing number} until the filename is * unique. * - FILE_EXISTS_ERROR - Do nothing and return FALSE. + * * @return * File object if the copy is successful, or FALSE in the event of an error. * @@ -1070,7 +1071,7 @@ function file_unmanaged_delete_recursive($path) { function file_space_used($uid = NULL, $status = FILE_STATUS_PERMANENT) { $query = db_select('file', 'f'); // Use separate placeholders for the status to avoid a bug in some versions - // of PHP. @see http://drupal.org/node/352956 + // of PHP. See http://drupal.org/node/352956. $query->where('f.status & :status1 = :status2', array(':status1' => $status, ':status2' => $status)); $query->addExpression('SUM(f.filesize)', 'filesize'); if (!is_null($uid)) { @@ -1127,7 +1128,7 @@ function file_save_upload($source, $validators = array(), $destination = FALSE, // Check for file upload errors and return FALSE if a lower level system // error occurred. For a complete list of errors: - // @see http://php.net/manual/en/features.file-upload.errors.php + // See http://php.net/manual/en/features.file-upload.errors.php. switch ($_FILES['files']['error'][$source]) { case UPLOAD_ERR_INI_SIZE: case UPLOAD_ERR_FORM_SIZE: @@ -1734,8 +1735,8 @@ function file_upload_max_size() { * @return * The internet media type registered for the extension or * application/octet-stream for unknown extensions. - * @see - * file_default_mimetype_mapping() + * + * @see file_default_mimetype_mapping() */ function file_get_mimetype($uri, $mapping = NULL) { if ($wrapper = file_stream_wrapper_get_instance_by_uri($uri)) { @@ -1818,6 +1819,7 @@ function drupal_chmod($uri, $mode = NULL) { * @param $uri * A string containing the URI to verify. If this value is omitted, * Drupal's public files directory will be used [public://]. + * * @return * The absolute pathname, or FALSE on failure. * @@ -1853,6 +1855,7 @@ function drupal_realpath($uri) { * * @param $uri * A URI or path. + * * @return * A string containing the directory name. * @@ -1894,6 +1897,7 @@ function drupal_dirname($uri) { * Default to FALSE. * @param $context * Refer to http://php.net/manual/en/ref.stream.php + * * @return * Boolean TRUE on success, or FALSE on failure. * @@ -1929,6 +1933,7 @@ function drupal_mkdir($uri, $mode = NULL, $recursive = FALSE, $context = NULL) { * @param $prefix * The prefix of the generated temporary filename. * Note: Windows uses only the first three characters of prefix. + * * @return * The new temporary filename, or FALSE on failure. * diff --git a/includes/form.inc b/includes/form.inc index 35f86ef55..fe14c083b 100644 --- a/includes/form.inc +++ b/includes/form.inc @@ -61,6 +61,7 @@ * drupal_get_form(), including the unique form constructor function. For * example, the node_edit form requires that a node object is passed in here * when it is called. + * * @return * The form array. * @@ -191,9 +192,9 @@ function drupal_build_form($form_id, &$form_state) { if (!isset($form)) { // Record the filepath of the include file containing the original form, // so the form builder callbacks can be loaded when the form is being - // rebuilt from cache on a different path (such as 'system/ajax'). - // @see form_get_cache() - // menu_get_item() is not available at installation time. + // rebuilt from cache on a different path (such as 'system/ajax'). See + // form_get_cache(). + // $menu_get_item() is not available at installation time. if (!isset($form_state['build_info']['file']) && !defined('MAINTENANCE_MODE')) { $item = menu_get_item(); if (!empty($item['file'])) { @@ -357,7 +358,7 @@ function form_get_cache($form_build_id, &$form_state) { $form_state = $cached->data + $form_state; // If the original form is contained in an include file, load the file. - // @see drupal_build_form() + // See drupal_build_form(). if (!empty($form_state['build_info']['file']) && file_exists($form_state['build_info']['file'])) { require_once DRUPAL_ROOT . '/' . $form_state['build_info']['file']; } @@ -553,8 +554,7 @@ function drupal_retrieve_form($form_id, &$form_state) { // builder function to pre-populate the $form array with form elements, which // the actual form builder function ($callback) expects. This allows for // pre-populating a form with common elements for certain forms, such as - // back/next/save buttons in multi-step form wizards. - // @see drupal_build_form() + // back/next/save buttons in multi-step form wizards. See drupal_build_form(). if (isset($form_state['wrapper_callback']) && function_exists($form_state['wrapper_callback'])) { $form = call_user_func_array($form_state['wrapper_callback'], $args); // Put the prepopulated $form into $args. @@ -1088,7 +1088,7 @@ function form_execute_handlers($type, &$form, &$form_state) { * assume that certain data exists within $form_state['values'], and while not * doing anything with that data that requires it to be valid, PHP errors * would be triggered if the input processing and validation steps were fully - * skipped. @see http://drupal.org/node/370537. + * skipped. See http://drupal.org/node/370537. * * @return * Return value is for internal use only. To get a list of errors, use diff --git a/includes/menu.inc b/includes/menu.inc index a8df5ba87..5ce50daee 100644 --- a/includes/menu.inc +++ b/includes/menu.inc @@ -287,6 +287,7 @@ define('MENU_MAX_DEPTH', 9); * @param $parts * An array of path parts, for the above example * array('node', '12345', 'edit'). + * * @return * An array which contains the ancestors and placeholders. Placeholders * simply contain as many '%s' as the ancestors. @@ -341,6 +342,7 @@ function menu_get_ancestors($parts) { * A serialized array. * @param @map * An array of potential replacements. + * * @return * The $data array unserialized and mapped. */ @@ -383,6 +385,7 @@ function menu_set_item($path, $router_item) { * node/% item and return that. * @param $router_item * Internal use only. + * * @return * The router item, an associate array corresponding to one row in the * menu_router table. The value of key map holds the loaded objects. The @@ -492,6 +495,7 @@ function menu_execute_active_handler($path = NULL, $deliver = TRUE) { * A menu router or menu link item * @param $map * An array of path arguments (ex: array('node', '5')) + * * @return * Returns TRUE for success, FALSE if an object cannot be loaded. * Names of object loading functions are placed in $item['load_functions']. @@ -601,6 +605,7 @@ function _menu_check_access(&$item, $map) { * @param $link_translate * TRUE if we are translating a menu link item; FALSE if we are * translating a menu router item. + * * @return * No return value. * $item['title'] is localized according to $item['title_callback']. @@ -687,6 +692,7 @@ function _menu_item_localize(&$item, $map, $link_translate = FALSE) { * @param $to_arg * Execute $item['to_arg_functions'] or not. Use only if you want to render a * path from the menu table, for example tabs. + * * @return * Returns the map with objects loaded as defined in the * $item['load_functions']. $item['access'] becomes TRUE if the item is @@ -761,6 +767,7 @@ function menu_tail_to_arg($arg, $map, $index) { * * @param $item * A menu link + * * @return * Returns the map of path arguments with objects loaded as defined in the * $item['load_functions']. @@ -853,11 +860,12 @@ function menu_get_object($type = 'node', $position = 1, $path = NULL) { * Render a menu tree based on the current path. * * The tree is expanded based on the current path and dynamic paths are also - * changed according to the defined to_arg functions (for example the 'My account' - * link is changed from user/% to a link with the current user's uid). + * changed according to the defined to_arg functions (for example the 'My + * account' link is changed from user/% to a link with the current user's uid). * * @param $menu_name * The name of the menu. + * * @return * The rendered HTML of that menu on the current page. */ @@ -881,6 +889,7 @@ function menu_tree($menu_name) { * * @param $tree * A data structure representing the tree as returned from menu_tree_data. + * * @return * A structured array to be rendered by drupal_render(). */ @@ -1317,6 +1326,7 @@ function _menu_tree_check_access(&$tree) { * to the root of the menu tree. * @param $depth * The minimum depth of any link in the $links array. + * * @return * See menu_tree_page_data for a description of the data structure. */ @@ -1604,6 +1614,7 @@ function menu_secondary_menu() { * The name of the menu. * @param $level * Optional, the depth of the menu to be returned. + * * @return * An array of links of the specified menu and level. */ @@ -1651,6 +1662,7 @@ function menu_navigation_links($menu_name, $level = 0) { * * @param $level * The level of tasks you ask for. Primary tasks are 0, secondary are 1. + * * @return * An array containing * - tabs: Local tasks for the requested level: @@ -2036,6 +2048,7 @@ function menu_set_active_item($path) { * @param $new_trail * Menu trail to set, or NULL to use previously-set or calculated trail. If * supplying a trail, use the same format as the return value (see below). + * * @return * Path to menu root of the current page, as an array of menu link items, * starting with the site's home page. Each link item is an associative array @@ -2187,6 +2200,7 @@ function menu_get_active_title() { * * @param $mlid * The mlid of the menu item. + * * @return * A menu link, with $item['access'] filled and link translated for * rendering. @@ -2592,13 +2606,14 @@ function _menu_delete_item($item, $force = FALSE) { * @param $item * An array representing a menu link item. The only mandatory keys are * link_path and link_title. Possible keys are: - * - menu_name default is navigation - * - weight default is 0 - * - expanded whether the item is expanded. - * - options An array of options, @see l for more. - * - mlid Set to an existing value, or 0 or NULL to insert a new link. - * - plid The mlid of the parent. - * - router_path The path of the relevant router item. + * - menu_name: Default is navigation + * - weight: Default is 0 + * - expanded: Whether the item is expanded. + * - options: An array of options, see l() for more. + * - mlid: Set to an existing value, or 0 or NULL to insert a new link. + * - plid: The mlid of the parent. + * - router_path: The path of the relevant router item. + * * @return * The mlid of the saved menu link, or FALSE if the menu link could not be * saved. @@ -2820,6 +2835,7 @@ function _menu_set_expanded_menus() { * * @param $link_path * The path for we are looking up its router path. + * * @return * A path from $menu keys or empty if $link_path points to a nonexisting * place. @@ -2903,6 +2919,7 @@ function menu_link_maintain($module, $op, $link_path, $link_title) { * * @param $item * An array representing a menu link item. + * * @return * The relative depth, or zero. * @@ -3313,6 +3330,7 @@ function _menu_router_save($menu, $masks) { * If this is set to TRUE, the function will perform the access checks and * return the site offline status, but not log the user out or display any * messages. + * * @return * FALSE if the site is not in maintenance mode, the user login page is * displayed, or the user has the 'access site in maintenance mode' diff --git a/includes/module.inc b/includes/module.inc index 3d9108c89..10996eb65 100644 --- a/includes/module.inc +++ b/includes/module.inc @@ -536,7 +536,7 @@ function module_hook($module, $hook) { * @return * An array with the names of the modules which are implementing this hook. * - * @see module_implements_write_cache(). + * @see module_implements_write_cache() */ function module_implements($hook, $sort = FALSE, $reset = FALSE) { // Use the advanced drupal_static() pattern, since this is called very often. diff --git a/includes/registry.inc b/includes/registry.inc index 5af4d4aa1..c06dbe767 100644 --- a/includes/registry.inc +++ b/includes/registry.inc @@ -17,7 +17,7 @@ */ /** - * @see registry_update(). + * Does the work for registry_update(). */ function _registry_update() { diff --git a/includes/stream_wrappers.inc b/includes/stream_wrappers.inc index adb279b00..288c3979d 100644 --- a/includes/stream_wrappers.inc +++ b/includes/stream_wrappers.inc @@ -16,8 +16,8 @@ * delimiter is in general just ":", not "://". Because of this PHP limitation * and for consistency Drupal will only accept URIs of form "scheme://target". * - * @link http://www.faqs.org/rfcs/rfc3986.html - * @link http://bugs.php.net/bug.php?id=47070 + * @see http://www.faqs.org/rfcs/rfc3986.html + * @see http://bugs.php.net/bug.php?id=47070 */ /** diff --git a/includes/theme.inc b/includes/theme.inc index 65da03de3..a93dd0dd7 100644 --- a/includes/theme.inc +++ b/includes/theme.inc @@ -430,7 +430,7 @@ function _theme_process_registry(&$cache, $name, $type, $theme, $path) { } foreach ($prefixes as $prefix) { // Only use non-hook-specific variable processors for theming hooks - // implemented as templates. @see theme(). + // implemented as templates. See theme(). if (isset($info['template']) && function_exists($prefix . '_' . $phase)) { $info[$phase_key][] = $prefix . '_' . $phase; } @@ -467,7 +467,7 @@ function _theme_process_registry(&$cache, $name, $type, $theme, $path) { $cache[$hook][$phase_key] = array(); } // Only use non-hook-specific variable processors for theming hooks - // implemented as templates. @see theme(). + // implemented as templates. See theme(). if (isset($info['template']) && function_exists($name . '_' . $phase)) { $cache[$hook][$phase_key][] = $name . '_' . $phase; } @@ -1083,7 +1083,7 @@ function drupal_find_theme_templates($cache, $extension, $path) { } // Find templates that implement possible "suggestion" variants of registered - // theme hooks and add those as new registered theme hooks. @see + // theme hooks and add those as new registered theme hooks. See // drupal_find_theme_functions() for more information about suggestions and // the use of 'pattern' and 'base hook'. $patterns = array_keys($files); @@ -1788,8 +1788,8 @@ function theme_tablesort_indicator($variables) { * * @param $variables * An associative array containing: - * - type: Number representing the marker type to display. - * @see MARK_NEW, MARK_UPDATED, MARK_READ + * - type: Number representing the marker type to display. See MARK_NEW, + * MARK_UPDATED, MARK_READ. * * @return * A string containing the marker. @@ -1957,7 +1957,7 @@ function theme_more_link($variables) { * that the final string is safe to include directly in the output by using * check_plain() or filter_xss(). * - * @see theme_username(). + * @see theme_username() */ function template_preprocess_username(&$variables) { $account = $variables['account']; @@ -2009,7 +2009,7 @@ function template_preprocess_username(&$variables) { /** * Process variables for theme_username(). * - * @see theme_username(). + * @see theme_username() */ function template_process_username(&$variables) { // Finalize the link_options array for passing to the l() function. -- cgit v1.2.3