Ticket #5638: 5638.r8665.diff

formatting.php

@@ -1 +1 @@
 <?php
 /**
- * Main Wordpress Formatting API 
+ * Main Wordpress Formatting API.
  *
- * Handles many functions for formatting output
+ * Handles many functions for formatting output.
  *
  * @package WordPress
  **/
@@ -18 +18 @@
  * <code>
  * &#8217;cause today&#8217;s effort makes it worth tomorrow&#8217;s &#8220;holiday&#8221;&#8230;
  * </code>
- * Code within certain html blocks are skipped. 
+ * Code within certain html blocks are skipped.
  *
  * @since 0.71
  * @uses $wp_cockneyreplace Array of formatted entities for certain common phrases
@@ -76 +76 @@
 }
 
 /**
- * Accepts matches array from preg_replace_callback in wpautop() or a string
+ * Accepts matches array from preg_replace_callback in wpautop() or a string.
  *
- * Ensures that the contents of a <<pre>>...<</pre>> HTML block are not converted into paragraphs or line-breaks.
+ * Ensures that the contents of a <<pre>>...<</pre>> HTML block are not
+ * converted into paragraphs or line-breaks.
  *
  * @since 1.2.0
  *
- * @param array|string $matches The array or string 
+ * @param array|string $matches The array or string
  * @return string The pre block without paragraph/line-break conversion.
  */
 function clean_pre($matches) {
@@ -99 +100 @@
 }
 
 /**
- * Replaces double line-breaks with paragraph elements
+ * Replaces double line-breaks with paragraph elements.
  *
- * A group of regex replaces used to identify text formatted with newlines and replace
- * double line-breaks with HTML paragraph tags. The remaining line-breaks after conversion
- * become <<br />> tags, unless $br is set to '0' or 'false'. 
- * 
+ * A group of regex replaces used to identify text formatted with newlines and
+ * replace double line-breaks with HTML paragraph tags. The remaining
+ * line-breaks after conversion become <<br />> tags, unless $br is set to '0'
+ *  or 'false'.
  *
  * @since 0.71
  *
  * @param string $pee The text which has to be formatted.
- * @param int|bool $br Optional. If set, this will convert all remaining line-breaks after paragraphing. Default true. 
- * @return string Text which has been converted into correct paragraph tags. 
+ * @param int|bool $br Optional. If set, this will convert all remaining line-breaks after paragraphing. Default true.
+ * @return string Text which has been converted into correct paragraph tags.
  */
 function wpautop($pee, $br = 1) {
         $pee = $pee . "\n"; // just to make things a little easier, pad the end
@@ -179 +180 @@
 }
 
 /**
- * Converts a number of special characters into their HTML entities
+ * Converts a number of special characters into their HTML entities.
  *
- * Differs from htmlspecialchars as existing HTML entities will not be encoded. Specificically
- * changes: & to &#038;, < to &lt; and > to &gt;. 
+ * Differs from htmlspecialchars as existing HTML entities will not be encoded.
+ * Specificically changes: & to &#038;, < to &lt; and > to &gt;.
  *
- * $quotes can be set to 'single' to encode ' to &#039;, 'double' to encode " to &quot;, or '1' to do both. 
- * Default is 0 where no quotes are encoded. 
+ * $quotes can be set to 'single' to encode ' to &#039;, 'double' to encode " to
+ * &quot;, or '1' to do both. Default is 0 where no quotes are encoded.
  *
  * @since 1.2.2
  *
- * @param string $text The text which is to be encoded
- * @param mixed $quotes Optional. Converts single quotes if set to 'single', double if set to 'double' or both if otherwise set. Default 0. 
- * @return string The encoded text with HTML entities. 
+ * @param string $text The text which is to be encoded.
+ * @param mixed $quotes Optional. Converts single quotes if set to 'single', double if set to 'double' or both if otherwise set. Default 0.
+ * @return string The encoded text with HTML entities.
  */
 function wp_specialchars( $text, $quotes = 0 ) {
         // Like htmlspecialchars except don't double-encode HTML entities
@@ -264 +265 @@
 }
 
 /**
- * Replaces accents in a string
+ * Replaces accents in a string.
  *
  * {@internal Missing Long Description}}
  *
@@ -404 +405 @@
 }
 
 /**
- * Filters certain characters from the file name. 
+ * Filters certain characters from the file name.
  *
  * {@internal Missing Long Description}}
  *
@@ -426 +427 @@
 }
 
 /**
- * Removes characters from the username
+ * Removes characters from the username.
  *
- * If $strict is true, only alphanumeric characters (as well as _, space, ., -, @) are returned. 
+ * If $strict is true, only alphanumeric characters (as well as _, space, ., -,
+ * @) are returned.
  *
  * @since 2.0.0
  *
- * @param string $username The username to be sanitized. 
- * @param bool $strict If set limits $username to specific characters. Default false. 
- * @return string The sanitized username, after passing through filters. 
+ * @param string $username The username to be sanitized.
+ * @param bool $strict If set limits $username to specific characters. Default false.
+ * @return string The sanitized username, after passing through filters.
  */
 function sanitize_user( $username, $strict = false ) {
         $raw_username = $username;
@@ -451 +453 @@
 }
 
 /**
- * Returns a string which has been sanitized. 
+ * Returns a string which has been sanitized.
  *
- * Specifically, HTML and PHP tags are stripped. Further actions can be added via the
- * plugin API. If $title is empty and $fallback_title is set, the latter will be used. 
+ * Specifically, HTML and PHP tags are stripped. Further actions can be added
+ * via the plugin API. If $title is empty and $fallback_title is set, the latter
+ * will be used.
  *
  * @since 1.0.0
  *
- * @param string $title The string to be sanitized. 
- * @param string $fallback_title Optional. A title to use if $title is empty.  
- * @return string The sanitized string. 
+ * @param string $title The string to be sanitized.
+ * @param string $fallback_title Optional. A title to use if $title is empty.
+ * @return string The sanitized string.
  */
 function sanitize_title($title, $fallback_title = '') {
         $title = strip_tags($title);
@@ -473 +476 @@
 }
 
 /**
- * Replaces the string with safe characters. Whitespace becomes a dash. 
+ * Replaces the string with safe characters. Whitespace becomes a dash.
  *
- * Limits the output to alphanumeric characters, underscore (_) and dash (-). 
+ * Limits the output to alphanumeric characters, underscore (_) and dash (-).
  *
  * @since 1.2.0
  *
@@ -510 +513 @@
 }
 
 /**
- * Ensures a string is a valid SQL order by clause. 
+ * Ensures a string is a valid SQL order by clause.
  *
- * Accepts one or more columns, with or without ASC/DESC, and also accepts RAND()
+ * Accepts one or more columns, with or without ASC/DESC, and also accepts
+ * RAND().
  *
  * @since 2.5.1
  *
@@ -527 +531 @@
 }
 
 /**
- * Converts a number of characters from a string
+ * Converts a number of characters from a string.
  *
- * Metadata tags <<title>> and <<category>> are removed, <<br>> and <<hr>> are converted into correct
- * XHTML and Unicode characters are converted to the valid range. 
+ * Metadata tags <<title>> and <<category>> are removed, <<br>> and <<hr>> are
+ * converted into correct XHTML and Unicode characters are converted to the
+ * valid range.
  *
  * @since 0.71
  *
@@ -593 +598 @@
 }
 
 /**
- * Fixes javascript bugs in browsers. 
+ * Fixes javascript bugs in browsers.
  *
  * {@internal Missing Long Description}}
  *
@@ -751 +756 @@
 }
 
 /**
- * Acts on text which is about to be edited
+ * Acts on text which is about to be edited.
  *
- * Unless $richedit is set, it is simply a holder for the 'format_to_edit' filter. If $richedit
- * is set true htmlspecialchars() will be run on the content, converting special characters to 
- * HTMl entities. 
+ * Unless $richedit is set, it is simply a holder for the 'format_to_edit'
+ * filter. If $richedit is set true htmlspecialchars() will be run on the
+ * content, converting special characters to HTMl entities.
  *
  * @since 0.71
  *
- * @param string $content The text about to be edited. 
- * @param bool $richedit Whether or not the $content should pass through htmlspecialchars(). Default false. 
- * @return string The text after the filter (and possibly htmlspecialchars()) has been run. 
+ * @param string $content The text about to be edited.
+ * @param bool $richedit Whether or not the $content should pass through htmlspecialchars(). Default false.
+ * @return string The text after the filter (and possibly htmlspecialchars()) has been run.
  */
 function format_to_edit($content, $richedit = false) {
         $content = apply_filters('format_to_edit', $content);
@@ -778 +783 @@
  * @since 0.71
  *
  * @param string $content The text to pass through the filter.
- * @return string Text returned from the 'format_to_post' filter. 
+ * @return string Text returned from the 'format_to_post' filter.
  */
 function format_to_post($content) {
         $content = apply_filters('format_to_post', $content);
@@ -786 +791 @@
 }
 
 /**
- * Add leading zeros when necessary
+ * Add leading zeros when necessary.
  *
  * {@internal Missing Long Description}}
  *
@@ -817 +822 @@
 }
 
 /**
- * Appends a trailing slash
+ * Appends a trailing slash.
  *
- * Will remove trailing slash if it exists already before adding
- * a trailing slash. This prevents double slashing a string or
- * path.
+ * Will remove trailing slash if it exists already before adding a trailing
+ * slash. This prevents double slashing a string or path.
  *
- * The primary use of this is for paths and thus should be used
- * for paths. It is not restricted to paths and offers no specific
- * path support.
+ * The primary use of this is for paths and thus should be used for paths. It is
+ * not restricted to paths and offers no specific path support.
  *
  * @since 1.2.0
  * @uses untrailingslashit() Unslashes string if it was slashed already
@@ -838 +841 @@
 }
 
 /**
- * Removes trailing slash if it exists
+ * Removes trailing slash if it exists.
  *
- * The primary use of this is for paths and thus should be used
- * for paths. It is not restricted to paths and offers no specific
- * path support.
+ * The primary use of this is for paths and thus should be used for paths. It is
+ * not restricted to paths and offers no specific path support.
  *
  * @since 2.2.0
  *
@@ -942 +944 @@
  *
  * {@internal Missing Long Description}}
  *
- * @since 2.5
+ * @since 2.5.0
  * @access private
  *
  * @param unknown_type $matches
@@ -967 +969 @@
  *
  * {@internal Missing Long Description}}
  *
- * @since 2.5
+ * @since 2.5.0
  * @access private
  *
  * @param unknown_type $matches
@@ -993 +995 @@
  *
  * {@internal Missing Long Description}}
  *
- * @since 2.5
+ * @since 2.5.0
  * @access private
  *
  * @param unknown_type $matches
@@ -1138 +1140 @@
 }
 
 /**
- * get_gmt_from_date() - Give it a date, it will give you the same date as GMT
+ * Give it a date, it will give you the same date as GMT.
  *
  * {@internal Missing Long Description}}
  *
@@ -1156 +1158 @@
 }
 
 /**
- * get_date_from_gmt() - Give it a GMT date, it will give you the same date with $time_difference added
+ * Give it a GMT date, it will give you the same date with $time_difference added.
  *
  * {@internal Missing Long Description}}
  *
@@ -1174 +1176 @@
 }
 
 /**
- * iso8601_timezone_to_offset() - Computes an offset in seconds from an iso8601 timezone
+ * Computes an offset in seconds from an iso8601 timezone.
  *
  * {@internal Missing Long Description}}
  *
@@ -1197 +1199 @@
 }
 
 /**
- * iso8601_to_datetime() - Converts an iso8601 date to MySQL DateTime format used by post_date[_gmt]
+ * Converts an iso8601 date to MySQL DateTime format used by post_date[_gmt].
  *
  * {@internal Missing Long Description}}
  *
@@ -1229 +1231 @@
 }
 
 /**
- * Adds a element attributes to open links in new windows
+ * Adds a element attributes to open links in new windows.
  *
- * Comment text in popup windows should be filtered through this. Right
- * now it's a moderately dumb function, ideally it would detect whether
- * a target or rel attribute was already there and adjust its actions
- * accordingly.
+ * Comment text in popup windows should be filtered through this. Right now it's
+ * a moderately dumb function, ideally it would detect whether a target or rel
+ * attribute was already there and adjust its actions accordingly.
  *
  * @since 0.71
  *
@@ -1247 +1248 @@
 }
 
 /**
- * Strips out all characters that are not allowable in an email
+ * Strips out all characters that are not allowable in an email.
  *
  * @since 1.5.0
  *
@@ -1620 +1621 @@
         return apply_filters('richedit_pre', $output);
 }
 
+/**
+ * {@internal Missing Short Description}}
+ *
+ * {@internal Missing Long Description}}
+ *
+ * @since unknown
+ *
+ * @param string $output {@internal Missing Description}}
+ * @return string {@internal Missing Description}}
+ */
 function wp_htmledit_pre($output) {
         if ( !empty($output) )
                 $output = htmlspecialchars($output, ENT_NOQUOTES); // convert only < > &
@@ -1683 +1694 @@
 }
 
 /**
- * Convert entities, while preserving already-encoded entities
+ * Convert entities, while preserving already-encoded entities.
  *
  * {@internal Missing Long Description}}
  *
@@ -1701 +1712 @@
 }
 
 /**
- * Escape single quotes, specialchar double quotes, and fix line endings
+ * Escape single quotes, specialchar double quotes, and fix line endings.
  *
  * {@internal Missing Long Description}}
  *
@@ -1717 +1728 @@
         return apply_filters('js_escape', $safe_text, $text);
 }
 
-// Escaping for HTML attributes
+/**
+ * Escaping for HTML attributes.
+ *
+ * @since unknown
+ *
+ * @param string $text
+ * @return string
+ */
 function attribute_escape($text) {
         $safe_text = wp_specialchars($text, true);
         return apply_filters('attribute_escape', $safe_text, $text);
 }
 
-// Escape a HTML tag name
+/**
+ * Escape a HTML tag name.
+ *
+ * @since unknown
+ *
+ * @param string $tag_name
+ * @return string
+ */
 function tag_escape($tag_name) {
         $safe_tag = strtolower( preg_replace('[^a-zA-Z_:]', '', $tag_name) );
         return apply_filters('tag_escape', $safe_tag, $tag_name);
 }
 
 /**
- * Escapes text for SQL LIKE special characters % and _
+ * Escapes text for SQL LIKE special characters % and _.
  *
+ * @since unknown
+ *
  * @param string text the text to be escaped
  * @return string text, safe for inclusion in LIKE query
  */
@@ -1739 +1766 @@
         return str_replace(array("%", "_"), array("\\%", "\\_"), $text);
 }
 
+/**
+ * {@internal Missing Short Description}}
+ *
+ * @since unknown
+ *
+ * @param string $link
+ * @return string
+ */
 function wp_make_link_relative( $link ) {
         return preg_replace('|https?://[^/]+(/.*)|i', '$1', $link );
 }
@@ -1835 +1870 @@
         $array = apply_filters( 'wp_parse_str', $array );
 }
 
-// Convert lone less than signs.  KSES already converts lone greater than signs.
+/**
+ * Convert lone less than signs.
+ *
+ * KSES already converts lone greater than signs.
+ *
+ * @since unknown
+ *
+ * @param string $text
+ * @return string
+ */
 function wp_pre_kses_less_than( $text ) {
         return preg_replace_callback('%<[^>]*?((?=<)|>|$)%', 'wp_pre_kses_less_than_callback', $text);
 }
 
+/**
+ * {@internal Missing Short Description}}
+ *
+ * @since unknown
+ *
+ * @param unknown_type $matches
+ * @return unknown
+ */
 function wp_pre_kses_less_than_callback( $matches ) {
         if ( false === strpos($matches[0], '>') )
                 return wp_specialchars($matches[0]);
@@ -1847 +1899 @@
 }
 
 /**
- * wp_sprintf() - sprintf() with filters
+ * WordPress implementation of PHP sprintf() with filters.
+ *
+ * @since unknown
+ *
+ * @param unknown_type $pattern
+ * @return unknown
  */
 function wp_sprintf( $pattern ) {
         $args = func_get_args( );
@@ -1902 +1959 @@
 }
 
 /**
- * wp_sprintf_l - List specifier %l for wp_sprintf
+ * List specifier %l for wp_sprintf.
  *
+ * @since unknown
+ *
  * @param unknown_type $pattern
  * @param unknown_type $args
  * @return unknown
@@ -1942 +2001 @@
 /**
  * Safely extracts not more than the first $count characters from html string
  *
- * UTF-8, tags and entities safe prefix extraction. Entities inside will *NOT* be
- * counted as one character. For example &amp; will be counted as 4, &lt; as 3, etc.
+ * UTF-8, tags and entities safe prefix extraction. Entities inside will *NOT*
+ * be counted as one character. For example &amp; will be counted as 4, &lt; as
+ * 3, etc.
  *
  * @param integer $str String to get the excerpt from
  * @param integer $count Maximum number of characters to take
@@ -1960 +2020 @@
 /**
  * Add a Base url to relative links in passed content.
  *
- * By default it supports the 'src' and 'href' attributes,
- * However this may be changed via the 3rd param.
+ * By default it supports the 'src' and 'href' attributes, However this may be
+ * changed via the 3rd param.
  *
- * @package WordPress
  * @since 2.7
  *
  * @param string $content String to search for links in
  * @param string $base The base URL to prefix to links
  * @param array $attrs The attributes which should be processed.
- * @eaturn string The processed content.
+ * @return string The processed content.
  */
 function links_add_base_url( $content, $base, $attrs = array('src', 'href') ) {
         $attrs = implode('|', (array)$attrs);
@@ -1981 +2040 @@
 /**
  * Callback to add a base url to relative links in passed content.
  *
- *
- * @package WordPress
  * @since 2.7
+ * @access private
  *
- * @internal
  * @param string $m The matched link
  * @param string $base The base URL to prefix to links
- * @eaturn string The processed link
+ * @return string The processed link
  */
 function _links_add_base($m, $base) {
         //1 = attribute name  2 = quotation mark  3 = URL
@@ -2002 +2059 @@
 /**
  * Adds a Target attribute to all links in passed content.
  *
- * This function by default only applies to <a> tags,
- * however this can be modified by the 3rd param.
+ * This function by default only applies to <a> tags, however this can be
+ * modified by the 3rd param.
+ *
  * NOTE: Any current target attributed will be striped and replaced.
  *
- * @package WordPress
  * @since 2.7
  *
  * @param string $content String to search for links in
  * @param string $target The Target to add to the links
  * @param array $tags An array of tags to apply to.
- * @eaturn string The processed content.
+ * @return string The processed content.
  */
 function links_add_target( $content, $target = '_blank', $tags = array('a') ) {
         $tags = implode('|', (array)$tags);
@@ -2021 +2078 @@
                         $content);
 }
 /**
- * Callback to add a target attribute to all links in passed content
+ * Callback to add a target attribute to all links in passed content.
  *
- *
- * @package WordPress
  * @since 2.7
+ * @access private
  *
- * @internal
  * @param string $m The matched link
  * @param string $target The Target to add to the links
- * @eaturn string The processed link.
+ * @return string The processed link.
  */
 function _links_add_target( $m, $target ) {
         $tag = $m[1];