diff --git a/modules/system/system.api.php b/modules/system/system.api.php
index fa12ae3..d682dff 100644
--- a/modules/system/system.api.php
+++ b/modules/system/system.api.php
@@ -4340,7 +4340,11 @@ function hook_url_outbound_alter(&$path, &$options, $original_path) {
  *   "http://example.com/foo". After the url() function is called to construct
  *   the URL from $path and $options, the resulting URL is passed through
  *   check_plain() before it is inserted into the HTML anchor tag, to ensure
- *   well-formed HTML. See url() for more information and notes.
+ *   well-formed HTML. See url() for more information and notes. While it is
+ *   possible to change this parameter from this alter,
+ *   hook_url_outbound_alter() is almost always better for this purpose since
+ *   that one also fires when the resulting URL is not (immediately) used as a
+ *   link.
  * @param array $options
  *   An associative array of additional options. Defaults to an empty array. It
  *   may contain the following elements.
@@ -4361,7 +4365,7 @@ function hook_url_outbound_alter(&$path, &$options, $original_path) {
  *
  * @see url()
  */
-function hook_link_alter($text, &$path, &$options) {
+function hook_link_alter(&$text, &$path, &$options) {
   // Use an external RSS feed rather than the Drupal one.
   if ($path == 'rss.xml') {
     $path = 'http://example.com/rss.xml';