- Patch #681538 by aspilicious, jhodgdon, trevjs: fixed possibly broken @see also links.

10 files changed, 80 insertions, 51 deletions

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.