WordPress.org
Get WordPress

Make WordPress Core

Ticket #5638: 5638.r8780.diff

File 5638.r8780.diff, 20.0 KB (added by jacobsantos, 16 years ago)

Corrected inline documentation (@since tags and formatting) based off of r8780

  • formatting.php

     
    5151        $dynamic_replacements = array('’$1','$1‘', '$1″', '$1′', '$1’$2', '$1“$2', '”$1', '’$1', '$1×$2');
    5252
    5353        for ( $i = 0; $i < $stop; $i++ ) {
    54                 $curl = $textarr[$i];
     54                $curl = $textarr[$i];
    5555
    5656                if ( !empty($curl) && '<' != $curl{0} && '[' != $curl{0} && $next && !$has_pre_parent) { // If it's not a tag
    5757                        // static strings
    … …  
    7272                $output .= $curl;
    7373        }
    7474
    75         return $output;
     75        return $output;
    7676}
    7777
    7878/**
    … …  
    105105 * A group of regex replaces used to identify text formatted with newlines and
    106106 * replace double line-breaks with HTML paragraph tags. The remaining
    107107 * line-breaks after conversion become <<br />> tags, unless $br is set to '0'
    108  *  or 'false'.
     108 * or 'false'.
    109109 *
    110110 * @since 0.71
    111111 *
    … …  
    154154/**
    155155 * Checks to see if a string is utf8 encoded.
    156156 *
    157  * {@internal Missing Long Description}}
    158  *
    159157 * @since 1.2.1
    160158 *
    161159 * @param string $Str The string to be checked
    … …  
    183181 * Converts a number of special characters into their HTML entities.
    184182 *
    185183 * Differs from htmlspecialchars as existing HTML entities will not be encoded.
    186  * Specificically changes: & to &#038;, < to &lt; and > to &gt;.
     184 * Specifically changes: & to &#038;, < to &lt; and > to &gt;.
    187185 *
    188186 * $quotes can be set to 'single' to encode ' to &#039;, 'double' to encode " to
    189187 * &quot;, or '1' to do both. Default is 0 where no quotes are encoded.
    … …  
    267265/**
    268266 * Replaces accents in a string.
    269267 *
    270  * {@internal Missing Long Description}}
    271  *
    272268 * @since 1.2.1
    273269 *
    274270 * @param string $string The text to be filtered.
    … …  
    423419        $name = preg_replace('|-+|', '-', $name);
    424420        $name = trim($name, '-');
    425421        return $name;
    426        
    427422}
    428423
    429424/**
    430  * Removes characters from the username.
     425 * Sanitize username stripping out unsafe characters.
    431426 *
    432427 * If $strict is true, only alphanumeric characters (as well as _, space, ., -,
    433428 * @) are returned.
    … …  
    456451}
    457452
    458453/**
    459  * Returns a string which has been sanitized.
     454 * Sanitizes title or use fallback title.
    460455 *
    461456 * Specifically, HTML and PHP tags are stripped. Further actions can be added
    462457 * via the plugin API. If $title is empty and $fallback_title is set, the latter
    … …  
    479474}
    480475
    481476/**
    482  * Replaces the string with safe characters. Whitespace becomes a dash.
     477 * Sanitizes title, replacing whitespace with dashes.
    483478 *
    484479 * Limits the output to alphanumeric characters, underscore (_) and dash (-).
     480 * Whitespace becomes a dash.
    485481 *
    486482 * @since 1.2.0
    487483 *
    … …  
    603599/**
    604600 * Fixes javascript bugs in browsers.
    605601 *
    606  * {@internal Missing Long Description}}
     602 * Converts unicode characters to HTML numbered entities.
    607603 *
    608604 * @since 1.5.0
    609605 * @uses $is_macIE
    … …  
    616612        // Fixes for browsers' javascript bugs
    617613        global $is_macIE, $is_winIE;
    618614
     615        /** @todo use preg_replace_callback() instead */
    619616        if ( $is_winIE || $is_macIE )
    620617                $text =  preg_replace("/\%u([0-9A-F]{4,4})/e",  "'&#'.base_convert('\\1',16,10).';'", $text);
    621618
    … …  
    623620}
    624621
    625622/**
    626  * balanceTags() - {@internal Missing Short Description}}
     623 * Will only balance the tags if forced to and the option is set to balance tags.
    627624 *
    628  * {@internal Missing Long Description}}
     625 * The option 'use_balanceTags' is used for whether the tags will be balanced.
     626 * Both the $force parameter and 'use_balanceTags' option will have to be true
     627 * before the tags will be balanced.
    629628 *
    630629 * @since 0.71
    631630 *
    … …  
    796795/**
    797796 * Add leading zeros when necessary.
    798797 *
    799  * {@internal Missing Long Description}}
     798 * If you set the threshold to '4' and the number is '10', then you will get
     799 * back '0010'. If you set the number to '4' and the number is '5000', then you
     800 * will get back '5000'.
    800801 *
    801802 * @since 0.71
    802803 *
    … …  
    804805 * @param int $threshold Amount of digits
    805806 * @return string Adds leading zeros to number if needed
    806807 */
    807 function zeroise($number,$threshold) {
     808function zeroise($number, $threshold) {
    808809        return sprintf('%0'.$threshold.'s', $number);
    809810}
    810811
    811812/**
    812813 * Adds backslashes before letters and before a number at the start of a string.
    813814 *
    814  * {@internal Missing Long Description}}
    815  *
    816815 * @since 0.71
    817816 *
    818817 * @param string $string Value to which backslashes will be added.
    … …  
    861860/**
    862861 * Adds slashes to escape strings.
    863862 *
    864  * Slashes will first be removed if magic_quotes_gpc is set,
    865  * see {@link http://www.php.net/magic_quotes} for more details.
     863 * Slashes will first be removed if magic_quotes_gpc is set, see {@link
     864 * http://www.php.net/magic_quotes} for more details.
    866865 *
    867866 * @since 0.71
    868867 *
    … …  
    882881/**
    883882 * Navigates through an array and removes slashes from the values.
    884883 *
    885  * If an array is passed, the array_map() function causes a callback to
    886  * pass the value back to the function. The slashes from this value will
    887  * removed.
     884 * If an array is passed, the array_map() function causes a callback to pass the
     885 * value back to the function. The slashes from this value will removed.
    888886 *
    889887 * @since 2.0.0
    890888 *
    … …  
    892890 * @return array|string Stripped array (or string in the callback).
    893891 */
    894892function stripslashes_deep($value) {
    895          $value = is_array($value) ?
    896                  array_map('stripslashes_deep', $value) :
    897                  stripslashes($value);
    898 
    899          return $value;
     893        $value = is_array($value) ? array_map('stripslashes_deep', $value) : stripslashes($value);
     894        return $value;
    900895}
    901896
    902897/**
    … …  
    911906 * @return array|string $value The encoded array (or string from the callback).
    912907 */
    913908function urlencode_deep($value) {
    914          $value = is_array($value) ?
    915                  array_map('urlencode_deep', $value) :
    916                  urlencode($value);
    917 
    918          return $value;
     909        $value = is_array($value) ? array_map('urlencode_deep', $value) : urlencode($value);
     910        return $value;
    919911}
    920912
    921913/**
    … …  
    947939}
    948940
    949941/**
    950  * _make_url_clickable_cb() - {@internal Missing Short Description}}
     942 * Callback to convert URI match to HTML A element.
    951943 *
    952  * {@internal Missing Long Description}}
     944 * This function was backported from 2.5.0 to 2.3.2. Regex callback for {@link
     945 * make_clickable()}.
    953946 *
    954  * @since 2.5.0
     947 * @since 2.3.2
    955948 * @access private
    956949 *
    957  * @param unknown_type $matches
    958  * @return unknown
     950 * @param array $matches Single Regex Match.
     951 * @return string HTML A element with URI address.
    959952 */
    960953function _make_url_clickable_cb($matches) {
    961954        $ret = '';
    … …  
    972965}
    973966
    974967/**
    975  * _make_web_ftp_clickable_cb() - {@internal Missing Short Description}}
     968 * Callback to convert URL match to HTML A element.
    976969 *
    977  * {@internal Missing Long Description}}
     970 * This function was backported from 2.5.0 to 2.3.2. Regex callback for {@link
     971 * make_clickable()}.
    978972 *
    979  * @since 2.5.0
     973 * @since 2.3.2
    980974 * @access private
    981975 *
    982  * @param unknown_type $matches
    983  * @return unknown
     976 * @param array $matches Single Regex Match.
     977 * @return string HTML A element with URL address.
    984978 */
    985979function _make_web_ftp_clickable_cb($matches) {
    986980        $ret = '';
    … …  
    998992}
    999993
    1000994/**
    1001  * _make_email_clickable_cb() - {@internal Missing Short Description}}
     995 * Callback to convert email address match to HTML A element.
    1002996 *
    1003  * {@internal Missing Long Description}}
     997 * This function was backported from 2.5.0 to 2.3.2. Regex callback for {@link
     998 * make_clickable()}.
    1004999 *
    1005  * @since 2.5.0
     1000 * @since 2.3.2
    10061001 * @access private
    10071002 *
    1008  * @param unknown_type $matches
    1009  * @return unknown
     1003 * @param array $matches Single Regex Match.
     1004 * @return string HTML A element with email address.
    10101005 */
    10111006function _make_email_clickable_cb($matches) {
    10121007        $email = $matches[2] . '@' . $matches[3];
    … …  
    10141009}
    10151010
    10161011/**
    1017  * make_clickable() - {@internal Missing Short Description}}
     1012 * Convert plaintext URI to HTML links.
    10181013 *
    1019  * {@internal Missing Long Description}}
     1014 * Converts URI, www and ftp, and email addresses. Finishes by fixing links
     1015 * within links.
    10201016 *
    10211017 * @since 0.71
    10221018 *
    1023  * @param unknown_type $ret
    1024  * @return unknown
     1019 * @param string $ret Content to convert URIs.
     1020 * @return string Content with converted URIs.
    10251021 */
    10261022function make_clickable($ret) {
    10271023        $ret = ' ' . $ret;
    … …  
    10771073 *
    10781074 * @since 0.71
    10791075 *
    1080  * @param unknown_type $text
    1081  * @return unknown
     1076 * @param string $text
     1077 * @return string
    10821078 */
    10831079function convert_smilies($text) {
    10841080        global $wp_smiliessearch, $wp_smiliesreplace;
    … …  
    11041100/**
    11051101 * Checks to see if the text is a valid email address.
    11061102 *
    1107  * {@internal Missing Long Description}}
    1108  *
    11091103 * @since 0.71
    11101104 *
    11111105 * @param string $user_email The email address to be checked.
    … …  
    11491143/**
    11501144 * Returns a date in the GMT equivalent.
    11511145 *
    1152  * Requires and returns a date in the Y-m-d H:i:s format.
    1153  * Simply subtracts the value of gmt_offset.
     1146 * Requires and returns a date in the Y-m-d H:i:s format. Simply subtracts the
     1147 * value of gmt_offset.
    11541148 *
    11551149 * @since 1.2.0
    11561150 *
    … …  
    11671161/**
    11681162 * Converts a GMT date into the correct format for the blog.
    11691163 *
    1170  * Requires and returns in the Y-m-d H:i:s format. Simply
    1171  * adds the value of gmt_offset.
     1164 * Requires and returns in the Y-m-d H:i:s format. Simply adds the value of
     1165 * gmt_offset.
    11721166 *
    11731167 * @since 1.2.0
    11741168 *
    … …  
    11851179/**
    11861180 * Computes an offset in seconds from an iso8601 timezone.
    11871181 *
    1188  * {@internal Missing Long Description}}
    1189  *
    11901182 * @since 1.5.0
    11911183 *
    11921184 * @param string $timezone Either 'Z' for 0 offset or '±hhmm'.
    … …  
    12081200/**
    12091201 * Converts an iso8601 date to MySQL DateTime format used by post_date[_gmt].
    12101202 *
    1211  * {@internal Missing Long Description}}
    1212  *
    12131203 * @since 1.5.0
    12141204 *
    12151205 * @param string $date_string Date and time in ISO 8601 format {@link http://en.wikipedia.org/wiki/ISO_8601}.
    1216  * @param unknown_type $timezone Optional. If set to GMT returns the time minus gmt_offset. Default USER.
     1206 * @param string $timezone Optional. If set to GMT returns the time minus gmt_offset. Default is 'user'.
    12171207 * @return string The date and time in MySQL DateTime format - Y-m-d H:i:s.
    12181208 */
    1219 function iso8601_to_datetime($date_string, $timezone = USER) {
    1220         if ($timezone == GMT) {
     1209function iso8601_to_datetime($date_string, $timezone = 'user') {
     1210        $timezone = strtolower($timezone);
    12211211
     1212        if ($timezone == 'gmt') {
     1213
    12221214                preg_match('#([0-9]{4})([0-9]{2})([0-9]{2})T([0-9]{2}):([0-9]{2}):([0-9]{2})(Z|[\+|\-][0-9]{2,4}){0,1}#', $date_string, $date_bits);
    12231215
    12241216                if (!empty($date_bits[7])) { // we have a timezone, so let's compute an offset
    … …  
    12321224
    12331225                return gmdate('Y-m-d H:i:s', $timestamp);
    12341226
    1235         } else if ($timezone == USER) {
     1227        } else if ($timezone == 'user') {
    12361228                return preg_replace('#([0-9]{4})([0-9]{2})([0-9]{2})T([0-9]{2}):([0-9]{2}):([0-9]{2})(Z|[\+|\-][0-9]{2,4}){0,1}#', '$1-$2-$3 $4:$5:$6', $date_string);
    12371229        }
    12381230}
    … …  
    12691261/**
    12701262 * Determines the difference between two timestamps.
    12711263 *
    1272  * The difference is returned in a human readable format such as
    1273  * "1 hour", "5 mins", "2 days".
     1264 * The difference is returned in a human readable format such as "1 hour",
     1265 * "5 mins", "2 days".
    12741266 *
    12751267 * @since 1.5.0
    12761268 *
    … …  
    13051297}
    13061298
    13071299/**
    1308  * Generates an excerpt from the content if needed.
     1300 * Generates an excerpt from the content, if needed.
    13091301 *
    1310  * {@internal Missing Long Description}}
     1302 * The excerpt word amount will be 55 words and if the amount is greater than
     1303 * that, then the string '[...]' will be appended to the excerpt. If the string
     1304 * is less than 55 words, then the content will be returned as is.
    13111305 *
    13121306 * @since 1.5.0
    13131307 *
    13141308 * @param string $text The exerpt. If set to empty an excerpt is generated.
    13151309 * @return string The excerpt.
    13161310 */
    1317 function wp_trim_excerpt($text) { // Fakes an excerpt if needed
     1311function wp_trim_excerpt($text) {
    13181312        if ( '' == $text ) {
    13191313                $text = get_the_content('');
    13201314
    … …  
    13371331/**
    13381332 * Converts named entities into numbered entities.
    13391333 *
    1340  * {@internal Missing Long Description}}
    1341  *
    13421334 * @since 1.5.1
    13431335 *
    13441336 * @param string $text The text within which entities will be converted.
    … …  
    16091601}
    16101602
    16111603/**
    1612  * Formats text for the rich text editor and applies filter.
     1604 * Formats text for the rich text editor.
    16131605 *
    1614  * The filter 'richedit_pre' is applied here. If $text is empty
    1615  * the filter will be applied to an empty string.
     1606 * The filter 'richedit_pre' is applied here. If $text is empty the filter will
     1607 * be applied to an empty string.
    16161608 *
    16171609 * @since 2.0.0
    16181610 *
    … …  
    16311623}
    16321624
    16331625/**
    1634  * Formats text for the HTML editor and applies a filter.
     1626 * Formats text for the HTML editor.
    16351627 *
    1636  * Unless $output is empty it will pass through htmlspecialchars
    1637  * before the 'htmledit_pre' filter is applied.
     1628 * Unless $output is empty it will pass through htmlspecialchars before the
     1629 * 'htmledit_pre' filter is applied.
    16381630 *
    1639  * @since unknown
     1631 * @since 2.5.0
    16401632 *
    16411633 * @param string $output The text to be formatted.
    16421634 * @return string Formatted text after filter applied.
    … …  
    16511643/**
    16521644 * Checks and cleans a URL.
    16531645 *
    1654  * A number of characters are removed from the URL. If the URL is
    1655  * for displaying (the default behaviour) amperstands are also replaced.
    1656  * The 'clean_url' filter is applied to the returned cleaned URL.
     1646 * A number of characters are removed from the URL. If the URL is for displaying
     1647 * (the default behaviour) amperstands are also replaced. The 'clean_url' filter
     1648 * is applied to the returned cleaned URL.
    16571649 *
    16581650 * @since 1.2.0
    16591651 * @uses wp_kses_bad_protocol() To only permit protocols in the URL set
    1660  *      via $protocols or the common ones set in the function.
     1652 *              via $protocols or the common ones set in the function.
    16611653 *
    16621654 * @param string $url The URL to be cleaned.
    16631655 * @param array $protocols Optional. An array of acceptable protocols.
    … …  
    17111703/**
    17121704 * Convert entities, while preserving already-encoded entities.
    17131705 *
    1714  * {@internal Missing Long Description}}
    1715  *
    17161706 * @link http://www.php.net/htmlentities Borrowed from the PHP Manual user notes.
    17171707 *
    17181708 * @since 1.2.2
    … …  
    17461736/**
    17471737 * Escaping for HTML attributes.
    17481738 *
    1749  * @since unknown
     1739 * @since 2.0.6
    17501740 *
    17511741 * @param string $text
    17521742 * @return string
    … …  
    17591749/**
    17601750 * Escape a HTML tag name.
    17611751 *
    1762  * @since unknown
     1752 * @since 2.5.0
    17631753 *
    17641754 * @param string $tag_name
    17651755 * @return string
    … …  
    17721762/**
    17731763 * Escapes text for SQL LIKE special characters % and _.
    17741764 *
    1775  * @since unknown
     1765 * @since 2.5.0
    17761766 *
    17771767 * @param string $text The text to be escaped.
    17781768 * @return string text, safe for inclusion in LIKE query.
    … …  
    17821772}
    17831773
    17841774/**
    1785  * {@internal Missing Short Description}}
     1775 * Convert full URL paths to absolute paths.
    17861776 *
    1787  * @since unknown
     1777 * Removes the http or https protocols and the domain. Keeps the path '/' at the
     1778 * beginning, so it isn't a true relative link, but from the web root base.
    17881779 *
    1789  * @param string $link
    1790  * @return string
     1780 * @since 2.1.0
     1781 *
     1782 * @param string $link Full URL path.
     1783 * @return string Absolute path.
    17911784 */
    17921785function wp_make_link_relative( $link ) {
    1793         return preg_replace('|https?://[^/]+(/.*)|i', '$1', $link );
     1786        return preg_replace( '|https?://[^/]+(/.*)|i', '$1', $link );
    17941787}
    17951788
    17961789/**
    17971790 * Sanitises various option values based on the nature of the option.
    17981791 *
    1799  * This is basically a switch statement which will pass $value through
    1800  * a number of functions depending on the $option.
     1792 * This is basically a switch statement which will pass $value through a number
     1793 * of functions depending on the $option.
    18011794 *
    18021795 * @since 2.0.5
    18031796 *
    … …  
    18051798 * @param string $value The unsanitised value.
    18061799 * @return string Sanitized value.
    18071800 */
    1808 function sanitize_option($option, $value) { // Remember to call stripslashes!
     1801function sanitize_option($option, $value) {
    18091802
    18101803        switch ($option) {
    18111804                case 'admin_email':
    … …  
    18821875/**
    18831876 * Parses a string into variables to be stored in an array.
    18841877 *
    1885  * Uses {@link http://www.php.net/parse_str parse_str()} and stripslashes
    1886  * if {@link http://www.php.net/magic_quotes magic_quotes_gpc} is on.
     1878 * Uses {@link http://www.php.net/parse_str parse_str()} and stripslashes if
     1879 * {@link http://www.php.net/magic_quotes magic_quotes_gpc} is on.
    18871880 *
    18881881 * @since 2.2.1
    18891882 * @uses apply_filters() for the 'wp_parse_str' filter.
    … …  
    19041897 * KSES already converts lone greater than signs.
    19051898 *
    19061899 * @uses wp_pre_kses_less_than_callback in the callback function.
    1907  * @since unknown
     1900 * @since 2.3.0
    19081901 *
    19091902 * @param string $text Text to be converted.
    19101903 * @return string Converted text.
    … …  
    19161909/**
    19171910 * Callback function used by preg_replace.
    19181911 *
    1919  * @since unknown
    19201912 * @uses wp_specialchars to format the $matches text.
     1913 * @since 2.3.0
    19211914 *
    19221915 * @param array $matches Populated by matches to preg_replace.
    19231916 * @return string The text returned after wp_specialchars if needed.
    … …  
    19311924/**
    19321925 * WordPress implementation of PHP sprintf() with filters.
    19331926 *
    1934  * @since unknown
     1927 * @since 2.5.0
    19351928 * @link http://www.php.net/sprintf
    19361929 *
    19371930 * @param string $pattern The string which formatted args are inserted.
    … …  
    19911984}
    19921985
    19931986/**
    1994  * List specifier %l for wp_sprintf.
     1987 * Localize list items before the rest of the content.
    19951988 *
    1996  * @since unknown
     1989 * The '%l' must be at the first characters can then contain the rest of the
     1990 * content. The list items will have ', ', ', and', and ' and ' added depending
     1991 * on the amount of list items in the $args parameter.
    19971992 *
    1998  * @param unknown_type $pattern
    1999  * @param unknown_type $args
    2000  * @return unknown
     1993 * @since 2.5.0
     1994 *
     1995 * @param string $pattern Content containing '%l' at the beginning.
     1996 * @param array $args List items to prepend to the content and replace '%l'.
     1997 * @return string Localized list items and rest of the content.
    20011998 */
    20021999function wp_sprintf_l($pattern, $args) {
    20032000        // Not a match
    … …  
    20202017        if ( count($args) == 1 )
    20212018                $result .= $l['between_only_two'] . array_shift($args);
    20222019        // Loop when more than two args
    2023         while ( count($args) ) {
     2020        // There is a bug in this code that doesn't meet the above comment's
     2021        // requirements.
     2022        while ( $i = count($args) ) {
    20242023                $arg = array_shift($args);
    20252024                if ( $i == 1 )
    20262025                        $result .= $l['between_last_two'] . $arg;
    … …  
    20372036 * be counted as one character. For example &amp; will be counted as 4, &lt; as
    20382037 * 3, etc.
    20392038 *
     2039 * @since 2.5.0
     2040 *
    20402041 * @param integer $str String to get the excerpt from.
    20412042 * @param integer $count Maximum number of characters to take.
    20422043 * @return string The excerpt.
    … …  
    20522053/**
    20532054 * Add a Base url to relative links in passed content.
    20542055 *
    2055  * By default it supports the 'src' and 'href' attributes,
    2056  * However this may be changed via the 3rd param.
     2056 * By default it supports the 'src' and 'href' attributes. However this can be
     2057 * changed via the 3rd param.
    20572058 *
    2058  * @package WordPress
    2059  * @since 2.7
     2059 * @since 2.7.0
    20602060 *
    20612061 * @param string $content String to search for links in.
    20622062 * @param string $base The base URL to prefix to links.
    … …  
    20732073/**
    20742074 * Callback to add a base url to relative links in passed content.
    20752075 *
     2076 * @since 2.7.0
     2077 * @access private
    20762078 *
    2077  * @package WordPress
    2078  * @since 2.7
    2079  *
    20802079 * @param string $m The matched link.
    20812080 * @param string $base The base URL to prefix to links.
    20822081 * @return string The processed link.
    … …  
    20932092/**
    20942093 * Adds a Target attribute to all links in passed content.
    20952094 *
    2096  * This function by default only applies to <a> tags,
    2097  * however this can be modified by the 3rd param.
    2098  * NOTE: Any current target attributed will be striped and replaced.
     2095 * This function by default only applies to <a> tags, however this can be
     2096 * modified by the 3rd param.
    20992097 *
    2100  * @package WordPress
    2101  * @since 2.7
     2098 * <b>NOTE:</b> Any current target attributed will be striped and replaced.
    21022099 *
     2100 * @since 2.7.0
     2101 *
    21032102 * @param string $content String to search for links in.
    21042103 * @param string $target The Target to add to the links.
    21052104 * @param array $tags An array of tags to apply to.
    … …  
    21142113/**
    21152114 * Callback to add a target attribute to all links in passed content.
    21162115 *
     2116 * @since 2.7.0
     2117 * @access private
    21172118 *
    2118  * @package WordPress
    2119  * @since 2.7
    2120  *
    21212119 * @param string $m The matched link.
    21222120 * @param string $target The Target to add to the links.
    21232121 * @return string The processed link.