- Patch #303987 by jhodgdon, CitizenKane: l() documentation needs to say something about encoding.

includes/common.inc

@@ -1900,21 +1900,37 @@ function format_username($account) {
  */
 
 /**
- * Generate a URL.
+ * Generates an internal or external URL.
+ *
+ * When creating links in modules, consider whether l() could be a better
+ * alternative than url().
  *
  * @param $path
- *   The Drupal path being linked to, such as "admin/content", or an existing
- *   URL like "http://drupal.org/". The special path '<front>' may also be given
- *   and will generate the site's base URL.
+ *   The internal path or external URL being linked to, such as "node/34" or
+ *   "http://example.com/foo". A few notes:
+ *   - If you provide a full URL, it will be considered an external URL.
+ *   - If you provide only the path (e.g. "node/34"), it will be
+ *     considered an internal link. In this case, it should be a system URL,
+ *     and it will be replaced with the alias, if one exists. Additional query
+ *     arguments for internal paths must be supplied in $options['query'], not
+ *     included in $path.
+ *   - If you provide an internal path and $options['alias'] is set to TRUE, the
+ *     path is assumed already to be the correct path alias, and the alias is
+ *     not looked up.
+ *   - The special string '<front>' generates a link to the site's base URL.
+ *   - If your external URL contains a query (e.g. http://example.com/foo?a=b),
+ *     then you can either URL encode the query keys and values yourself and
+ *     include them in $path, or use $options['query'] to let this function
+ *     URL encode them.
  * @param $options
- *   An associative array of additional options, with the following keys:
+ *   An associative array of additional options, with the following elements:
  *   - 'query': An array of query key/value-pairs (without any URL-encoding) to
- *     append to the link.
- *   - 'fragment': A fragment identifier (or named anchor) to append to the
- *     link. Do not include the leading '#' character.
+ *     append to the URL.
+ *   - 'fragment': A fragment identifier (named anchor) to append to the URL.
+ *     Do not include the leading '#' character.
  *   - 'absolute': Defaults to FALSE. Whether to force the output to be an
  *     absolute link (beginning with http:). Useful for links that will be
- *     displayed outside the site, such as in a RSS feed.
+ *     displayed outside the site, such as in an RSS feed.
  *   - 'alias': Defaults to FALSE. Whether the given path is a URL alias
  *     already.
  *   - 'external': Whether the given path is an external URL.
@@ -1933,9 +1949,6 @@ function format_username($account) {
  *
  * @return
  *   A string containing a URL to the given path.
- *
- * When creating links in modules, consider whether l() could be a better
- * alternative than url().
  */
 function url($path = NULL, array $options = array()) {
   // Merge in defaults.
@@ -2125,50 +2138,36 @@ function drupal_attributes(array $attributes = array()) {
 }
 
 /**
- * Format an internal Drupal link.
+ * Formats an internal or external URL link as an HTML anchor tag.
  *
- * This function correctly handles aliased paths, and allows themes to highlight
- * links to the current page correctly, so all internal links output by modules
- * should be generated by this function if possible.
+ * This function correctly handles aliased paths, and adds an 'active' class
+ * attribute to links that point to the current page (for theming), so all
+ * internal links output by modules should be generated by this function if
+ * possible.
  *
  * @param $text
- *   The text to be enclosed with the anchor tag.
+ *   The link text for the anchor tag.
  * @param $path
- *   The Drupal path being linked to, such as "admin/content". Can be an
- *   external or internal URL.
- *     - If you provide the full URL, it will be considered an external URL.
- *     - If you provide only the path (e.g. "admin/content"), it is
- *       considered an internal link. In this case, it must be a system URL
- *       as the url() function will generate the alias.
- *     - If you provide '<front>', it generates a link to the site's
- *       base URL (again via the url() function).
- *     - If you provide a path, and 'alias' is set to TRUE (see below), it is
- *       used as is.
- * @param $options
- *   An associative array of additional options, with the following keys:
- *     - attributes: An associative array of HTML attributes to apply to the
- *       anchor tag.
- *     - query: A query string to append to the link, or an array of query
- *       key/value properties.
- *     - fragment: A fragment identifier (named anchor) to append to the link.
- *       Do not include the '#' character.
- *     - absolute: (default FALSE) Whether to force the output to be an absolute
- *       link (beginning with http:). Useful for links that will be displayed
- *       outside the site, such as in an RSS feed.
- *     - html: (default FALSE) Whether $text is HTML, or just plain-text. For
- *       example for making an image a link, this must be set to TRUE, or else
- *       you will see the escaped HTML.
- *     - alias: (default FALSE) Whether the given path is an alias already.
- *     - language: An optional language object. If the path being linked to is
- *       internal to the site, $options['language'] is used to look up the alias
- *       for the URL, and to determine whether the link is "active", or pointing
- *       to the current page (the language as well as the path must match). If
- *       $options['language'] is omitted, the language defined by the current
- *       page's URL will be used; this depends on the site's language
- *       negotiation settings (sub-domain or URL prefix).
+ *   The internal path or external URL being linked to, such as "node/34" or
+ *   "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.
+ * @param array $options
+ *   An associative array of additional options, with the following elements:
+ *   - 'attributes': An associative array of HTML attributes to apply to the
+ *     anchor tag.
+ *   - 'html' (default FALSE): Whether $text is HTML or just plain-text. For
+ *     example, to make an image tag into a link, this must be set to TRUE, or
+ *     you will see the escaped HTML image tag.
+ *   - 'language': An optional language object. If the path being linked to is
+ *     internal to the site, $options['language'] is used to determine whether
+ *     the link is "active", or pointing to the current page (the language as
+ *     well as the path must match). This element is also used by url().
+ *   - Additional $options elements used by the url() function.
  *
  * @return
- *   an HTML string containing a link to the given path.
+ *   An HTML string containing a link to the given path.
  */
 function l($text, $path, array $options = array()) {
   global $language_url;