WordPress.org

Make WordPress Core

Changeset 8783


Ignore:
Timestamp:
08/30/2008 09:28:11 PM (10 years ago)
Author:
westi
Message:

phpDoc updates for formatting functions fixes #5638 props jacobsantos.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/wp-includes/formatting.php

    r8743 r8783  
    1111 * Replaces common plain text characters into formatted entities
    1212 *
    13  * As an example, 
     13 * As an example,
    1414 * <code>
    1515 * 'cause today's effort makes it worth tomorrow's "holiday"...
     
    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
     
    7373    }
    7474
    75     return $output;
     75    return $output;
    7676}
    7777
     
    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
     
    155155 * Checks to see if a string is utf8 encoded.
    156156 *
    157  * {@internal Missing Long Description}}
    158  *
    159157 * @since 1.2.1
    160158 *
     
    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
     
    267265/**
    268266 * Replaces accents in a string.
    269  *
    270  * {@internal Missing Long Description}}
    271267 *
    272268 * @since 1.2.1
     
    424420    $name = trim($name, '-');
    425421    return $name;
    426    
    427 }
    428 
    429 /**
    430  * Removes characters from the username.
     422}
     423
     424/**
     425 * Sanitize username stripping out unsafe characters.
    431426 *
    432427 * If $strict is true, only alphanumeric characters (as well as _, space, ., -,
     
    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
     
    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
     
    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
     
    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);
     
    624621
    625622/**
    626  * balanceTags() - {@internal Missing Short Description}}
    627  *
    628  * {@internal Missing Long Description}}
     623 * Will only balance the tags if forced to and the option is set to balance tags.
     624 *
     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
     
    643642 * Balances tags of string using a modified stack.
    644643 *
    645  * {@internal Missing Long Description}}
    646  *
    647644 * @since 2.0.4
    648645 *
    649646 * @author Leonard Lin <leonard@acm.org>
    650647 * @license GPL v2.0
    651  * @date November 4, 2001
     648 * @copyright November 4, 2001
    652649 * @version 1.1
    653650 * @todo Make better - change loop condition to $text in 1.2
     
    782779 * Holder for the 'format_to_post' filter.
    783780 *
    784  * {@internal Deprecated? Unused in 2.6}}
    785  *
    786781 * @since 0.71
    787782 *
     
    797792 * Add leading zeros when necessary.
    798793 *
    799  * {@internal Missing Long Description}}
     794 * If you set the threshold to '4' and the number is '10', then you will get
     795 * back '0010'. If you set the number to '4' and the number is '5000', then you
     796 * will get back '5000'.
    800797 *
    801798 * @since 0.71
     
    805802 * @return string Adds leading zeros to number if needed
    806803 */
    807 function zeroise($number,$threshold) {
     804function zeroise($number, $threshold) {
    808805    return sprintf('%0'.$threshold.'s', $number);
    809806}
     
    811808/**
    812809 * Adds backslashes before letters and before a number at the start of a string.
    813  *
    814  * {@internal Missing Long Description}}
    815810 *
    816811 * @since 0.71
     
    862857 * Adds slashes to escape strings.
    863858 *
    864  * Slashes will first be removed if magic_quotes_gpc is set,
    865  * see {@link http://www.php.net/magic_quotes} for more details.
     859 * Slashes will first be removed if magic_quotes_gpc is set, see {@link
     860 * http://www.php.net/magic_quotes} for more details.
    866861 *
    867862 * @since 0.71
     
    883878 * Navigates through an array and removes slashes from the values.
    884879 *
    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.
     880 * If an array is passed, the array_map() function causes a callback to pass the
     881 * value back to the function. The slashes from this value will removed.
    888882 *
    889883 * @since 2.0.0
     
    893887 */
    894888function stripslashes_deep($value) {
    895      $value = is_array($value) ?
    896          array_map('stripslashes_deep', $value) :
    897          stripslashes($value);
    898 
    899      return $value;
     889    $value = is_array($value) ? array_map('stripslashes_deep', $value) : stripslashes($value);
     890    return $value;
    900891}
    901892
     
    912903 */
    913904function urlencode_deep($value) {
    914      $value = is_array($value) ?
    915          array_map('urlencode_deep', $value) :
    916          urlencode($value);
    917 
    918      return $value;
     905    $value = is_array($value) ? array_map('urlencode_deep', $value) : urlencode($value);
     906    return $value;
    919907}
    920908
     
    948936
    949937/**
    950  * _make_url_clickable_cb() - {@internal Missing Short Description}}
    951  *
    952  * {@internal Missing Long Description}}
    953  *
    954  * @since 2.5.0
     938 * Callback to convert URI match to HTML A element.
     939 *
     940 * This function was backported from 2.5.0 to 2.3.2. Regex callback for {@link
     941 * make_clickable()}.
     942 *
     943 * @since 2.3.2
    955944 * @access private
    956945 *
    957  * @param unknown_type $matches
    958  * @return unknown
     946 * @param array $matches Single Regex Match.
     947 * @return string HTML A element with URI address.
    959948 */
    960949function _make_url_clickable_cb($matches) {
     
    973962
    974963/**
    975  * _make_web_ftp_clickable_cb() - {@internal Missing Short Description}}
    976  *
    977  * {@internal Missing Long Description}}
    978  *
    979  * @since 2.5.0
     964 * Callback to convert URL match to HTML A element.
     965 *
     966 * This function was backported from 2.5.0 to 2.3.2. Regex callback for {@link
     967 * make_clickable()}.
     968 *
     969 * @since 2.3.2
    980970 * @access private
    981971 *
    982  * @param unknown_type $matches
    983  * @return unknown
     972 * @param array $matches Single Regex Match.
     973 * @return string HTML A element with URL address.
    984974 */
    985975function _make_web_ftp_clickable_cb($matches) {
     
    999989
    1000990/**
    1001  * _make_email_clickable_cb() - {@internal Missing Short Description}}
    1002  *
    1003  * {@internal Missing Long Description}}
    1004  *
    1005  * @since 2.5.0
     991 * Callback to convert email address match to HTML A element.
     992 *
     993 * This function was backported from 2.5.0 to 2.3.2. Regex callback for {@link
     994 * make_clickable()}.
     995 *
     996 * @since 2.3.2
    1006997 * @access private
    1007998 *
    1008  * @param unknown_type $matches
    1009  * @return unknown
     999 * @param array $matches Single Regex Match.
     1000 * @return string HTML A element with email address.
    10101001 */
    10111002function _make_email_clickable_cb($matches) {
     
    10151006
    10161007/**
    1017  * make_clickable() - {@internal Missing Short Description}}
    1018  *
    1019  * {@internal Missing Long Description}}
     1008 * Convert plaintext URI to HTML links.
     1009 *
     1010 * Converts URI, www and ftp, and email addresses. Finishes by fixing links
     1011 * within links.
    10201012 *
    10211013 * @since 0.71
    10221014 *
    1023  * @param unknown_type $ret
    1024  * @return unknown
     1015 * @param string $ret Content to convert URIs.
     1016 * @return string Content with converted URIs.
    10251017 */
    10261018function make_clickable($ret) {
     
    10781070 * @since 0.71
    10791071 *
    1080  * @param unknown_type $text
    1081  * @return unknown
     1072 * @param string $text
     1073 * @return string
    10821074 */
    10831075function convert_smilies($text) {
     
    11051097 * Checks to see if the text is a valid email address.
    11061098 *
    1107  * {@internal Missing Long Description}}
    1108  *
    11091099 * @since 0.71
    11101100 *
     
    11261116
    11271117/**
    1128  * wp_iso_descrambler() - {@internal Missing Short Description}}
     1118 * {@internal Missing Short Description}}
    11291119 *
    11301120 * {@internal Missing Long Description}}
     
    11331123 * @usedby wp_mail() handles charsets in email subjects
    11341124 *
    1135  * @param unknown_type $string
    1136  * @return unknown
     1125 * @param string $string
     1126 * @return string
    11371127 */
    11381128function wp_iso_descrambler($string) {
     
    11421132    } else {
    11431133        $subject = str_replace('_', ' ', $matches[2]);
     1134        /** @todo use preg_replace_callback() */
    11441135        $subject = preg_replace('#\=([0-9a-f]{2})#ei', "chr(hexdec(strtolower('$1')))", $subject);
    11451136        return $subject;
     
    11501141 * Returns a date in the GMT equivalent.
    11511142 *
    1152  * Requires and returns a date in the Y-m-d H:i:s format.
    1153  * Simply subtracts the value of gmt_offset.
     1143 * Requires and returns a date in the Y-m-d H:i:s format. Simply subtracts the
     1144 * value of gmt_offset.
    11541145 *
    11551146 * @since 1.2.0
     
    11681159 * Converts a GMT date into the correct format for the blog.
    11691160 *
    1170  * Requires and returns in the Y-m-d H:i:s format. Simply
    1171  * adds the value of gmt_offset.
     1161 * Requires and returns in the Y-m-d H:i:s format. Simply adds the value of
     1162 * gmt_offset.
    11721163 *
    11731164 * @since 1.2.0
     
    11851176/**
    11861177 * Computes an offset in seconds from an iso8601 timezone.
    1187  *
    1188  * {@internal Missing Long Description}}
    11891178 *
    11901179 * @since 1.5.0
     
    12091198 * Converts an iso8601 date to MySQL DateTime format used by post_date[_gmt].
    12101199 *
    1211  * {@internal Missing Long Description}}
    1212  *
    12131200 * @since 1.5.0
    12141201 *
    12151202 * @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.
     1203 * @param string $timezone Optional. If set to GMT returns the time minus gmt_offset. Default is 'user'.
    12171204 * @return string The date and time in MySQL DateTime format - Y-m-d H:i:s.
    12181205 */
     
    12701257 * Determines the difference between two timestamps.
    12711258 *
    1272  * The difference is returned in a human readable format such as
    1273  * "1 hour", "5 mins", "2 days".
     1259 * The difference is returned in a human readable format such as "1 hour",
     1260 * "5 mins", "2 days".
    12741261 *
    12751262 * @since 1.5.0
     
    13061293
    13071294/**
    1308  * Generates an excerpt from the content if needed.
    1309  *
    1310  * {@internal Missing Long Description}}
     1295 * Generates an excerpt from the content, if needed.
     1296 *
     1297 * The excerpt word amount will be 55 words and if the amount is greater than
     1298 * that, then the string '[...]' will be appended to the excerpt. If the string
     1299 * is less than 55 words, then the content will be returned as is.
    13111300 *
    13121301 * @since 1.5.0
     
    13151304 * @return string The excerpt.
    13161305 */
    1317 function wp_trim_excerpt($text) { // Fakes an excerpt if needed
     1306function wp_trim_excerpt($text) {
    13181307    if ( '' == $text ) {
    13191308        $text = get_the_content('');
     
    13381327 * Converts named entities into numbered entities.
    13391328 *
    1340  * {@internal Missing Long Description}}
    1341  *
    13421329 * @since 1.5.1
    13431330 *
    13441331 * @param string $text The text within which entities will be converted.
    1345  * @return string Text with converted entities. 
     1332 * @return string Text with converted entities.
    13461333 */
    13471334function ent2ncr($text) {
     
    16101597
    16111598/**
    1612  * Formats text for the rich text editor and applies filter.
    1613  *
    1614  * The filter 'richedit_pre' is applied here. If $text is empty
    1615  * the filter will be applied to an empty string.
     1599 * Formats text for the rich text editor.
     1600 *
     1601 * The filter 'richedit_pre' is applied here. If $text is empty the filter will
     1602 * be applied to an empty string.
    16161603 *
    16171604 * @since 2.0.0
     
    16321619
    16331620/**
    1634  * Formats text for the HTML editor and applies a filter.
    1635  *
    1636  * Unless $output is empty it will pass through htmlspecialchars
    1637  * before the 'htmledit_pre' filter is applied.
    1638  *
    1639  * @since unknown
     1621 * Formats text for the HTML editor.
     1622 *
     1623 * Unless $output is empty it will pass through htmlspecialchars before the
     1624 * 'htmledit_pre' filter is applied.
     1625 *
     1626 * @since 2.5.0
    16401627 *
    16411628 * @param string $output The text to be formatted.
     
    16501637
    16511638/**
    1652  * Checks and cleans a URL. 
    1653  *
    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.
     1639 * Checks and cleans a URL.
     1640 *
     1641 * A number of characters are removed from the URL. If the URL is for displaying
     1642 * (the default behaviour) amperstands are also replaced. The 'clean_url' filter
     1643 * is applied to the returned cleaned URL.
    16571644 *
    16581645 * @since 1.2.0
    16591646 * @uses wp_kses_bad_protocol() To only permit protocols in the URL set
    1660  *  via $protocols or the common ones set in the function.
     1647 *      via $protocols or the common ones set in the function.
    16611648 *
    16621649 * @param string $url The URL to be cleaned.
    1663  * @param array $protocols Optional. An array of acceptable protocols. 
    1664  *      Defaults to 'http', 'https', 'ftp', 'ftps', 'mailto', 'news', 'irc', 'gopher', 'nntp', 'feed', 'telnet' if not set.
    1665  * @param string $context Optional. How the URL will be used. Default is 'display'. 
     1650 * @param array $protocols Optional. An array of acceptable protocols.
     1651 *      Defaults to 'http', 'https', 'ftp', 'ftps', 'mailto', 'news', 'irc', 'gopher', 'nntp', 'feed', 'telnet' if not set.
     1652 * @param string $context Optional. How the URL will be used. Default is 'display'.
    16661653 * @return string The cleaned $url after the 'cleaned_url' filter is applied.
    16671654 */
     
    17121699 * Convert entities, while preserving already-encoded entities.
    17131700 *
    1714  * {@internal Missing Long Description}}
    1715  *
    17161701 * @link http://www.php.net/htmlentities Borrowed from the PHP Manual user notes.
    17171702 *
     
    17471732 * Escaping for HTML attributes.
    17481733 *
    1749  * @since unknown
     1734 * @since 2.0.6
    17501735 *
    17511736 * @param string $text
     
    17601745 * Escape a HTML tag name.
    17611746 *
    1762  * @since unknown
     1747 * @since 2.5.0
    17631748 *
    17641749 * @param string $tag_name
     
    17731758 * Escapes text for SQL LIKE special characters % and _.
    17741759 *
    1775  * @since unknown
     1760 * @since 2.5.0
    17761761 *
    17771762 * @param string $text The text to be escaped.
     
    17831768
    17841769/**
    1785  * {@internal Missing Short Description}}
    1786  *
    1787  * @since unknown
    1788  *
    1789  * @param string $link
    1790  * @return string
     1770 * Convert full URL paths to absolute paths.
     1771 *
     1772 * Removes the http or https protocols and the domain. Keeps the path '/' at the
     1773 * beginning, so it isn't a true relative link, but from the web root base.
     1774 *
     1775 * @since 2.1.0
     1776 *
     1777 * @param string $link Full URL path.
     1778 * @return string Absolute path.
    17911779 */
    17921780function wp_make_link_relative( $link ) {
    1793     return preg_replace('|https?://[^/]+(/.*)|i', '$1', $link );
     1781    return preg_replace( '|https?://[^/]+(/.*)|i', '$1', $link );
    17941782}
    17951783
     
    17971785 * Sanitises various option values based on the nature of the option.
    17981786 *
    1799  * This is basically a switch statement which will pass $value through
    1800  * a number of functions depending on the $option.
     1787 * This is basically a switch statement which will pass $value through a number
     1788 * of functions depending on the $option.
    18011789 *
    18021790 * @since 2.0.5
     
    18061794 * @return string Sanitized value.
    18071795 */
    1808 function sanitize_option($option, $value) { // Remember to call stripslashes!
     1796function sanitize_option($option, $value) {
    18091797
    18101798    switch ($option) {
     
    18831871 * Parses a string into variables to be stored in an array.
    18841872 *
    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.
     1873 * Uses {@link http://www.php.net/parse_str parse_str()} and stripslashes if
     1874 * {@link http://www.php.net/magic_quotes magic_quotes_gpc} is on.
    18871875 *
    18881876 * @since 2.2.1
     
    19021890 * Convert lone less than signs.
    19031891 *
    1904  * KSES already converts lone greater than signs. 
     1892 * KSES already converts lone greater than signs.
    19051893 *
    19061894 * @uses wp_pre_kses_less_than_callback in the callback function.
    1907  * @since unknown
     1895 * @since 2.3.0
    19081896 *
    19091897 * @param string $text Text to be converted.
     
    19171905 * Callback function used by preg_replace.
    19181906 *
    1919  * @since unknown
    19201907 * @uses wp_specialchars to format the $matches text.
     1908 * @since 2.3.0
    19211909 *
    19221910 * @param array $matches Populated by matches to preg_replace.
     
    19321920 * WordPress implementation of PHP sprintf() with filters.
    19331921 *
    1934  * @since unknown
     1922 * @since 2.5.0
    19351923 * @link http://www.php.net/sprintf
    19361924 *
     
    19921980
    19931981/**
    1994  * List specifier %l for wp_sprintf.
    1995  *
    1996  * @since unknown
    1997  *
    1998  * @param unknown_type $pattern
    1999  * @param unknown_type $args
    2000  * @return unknown
     1982 * Localize list items before the rest of the content.
     1983 *
     1984 * The '%l' must be at the first characters can then contain the rest of the
     1985 * content. The list items will have ', ', ', and', and ' and ' added depending
     1986 * on the amount of list items in the $args parameter.
     1987 *
     1988 * @since 2.5.0
     1989 *
     1990 * @param string $pattern Content containing '%l' at the beginning.
     1991 * @param array $args List items to prepend to the content and replace '%l'.
     1992 * @return string Localized list items and rest of the content.
    20011993 */
    20021994function wp_sprintf_l($pattern, $args) {
     
    20382030 * 3, etc.
    20392031 *
     2032 * @since 2.5.0
     2033 *
    20402034 * @param integer $str String to get the excerpt from.
    20412035 * @param integer $count Maximum number of characters to take.
     
    20532047 * Add a Base url to relative links in passed content.
    20542048 *
    2055  * By default it supports the 'src' and 'href' attributes,
    2056  * However this may be changed via the 3rd param.
    2057  *
    2058  * @package WordPress
    2059  * @since 2.7
     2049 * By default it supports the 'src' and 'href' attributes. However this can be
     2050 * changed via the 3rd param.
     2051 *
     2052 * @since 2.7.0
    20602053 *
    20612054 * @param string $content String to search for links in.
     
    20742067 * Callback to add a base url to relative links in passed content.
    20752068 *
    2076  *
    2077  * @package WordPress
    2078  * @since 2.7
     2069 * @since 2.7.0
     2070 * @access private
    20792071 *
    20802072 * @param string $m The matched link.
     
    20942086 * Adds a Target attribute to all links in passed content.
    20952087 *
    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.
    2099  *
    2100  * @package WordPress
    2101  * @since 2.7
     2088 * This function by default only applies to <a> tags, however this can be
     2089 * modified by the 3rd param.
     2090 *
     2091 * <b>NOTE:</b> Any current target attributed will be striped and replaced.
     2092 *
     2093 * @since 2.7.0
    21022094 *
    21032095 * @param string $content String to search for links in.
     
    21152107 * Callback to add a target attribute to all links in passed content.
    21162108 *
    2117  *
    2118  * @package WordPress
    2119  * @since 2.7
     2109 * @since 2.7.0
     2110 * @access private
    21202111 *
    21212112 * @param string $m The matched link.
Note: See TracChangeset for help on using the changeset viewer.