Index: formatting.php =================================================================== --- formatting.php (revision 8665) +++ formatting.php (working copy) @@ -1,8 +1,8 @@ * ’cause today’s effort makes it worth tomorrow’s “holiday”… * - * 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,13 +76,14 @@ } /** - * 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 <
>...<
> HTML block are not converted into paragraphs or line-breaks. + * Ensures that the contents of a <
>...<
> 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,18 +100,18 @@ } /** - * 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 <
> 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 <
> 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,19 +180,19 @@ } /** - * 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 &, < to < and > to >. + * Differs from htmlspecialchars as existing HTML entities will not be encoded. + * Specificically changes: & to &, < to < and > to >. * - * $quotes can be set to 'single' to encode ' to ', 'double' to encode " to ", or '1' to do both. - * Default is 0 where no quotes are encoded. + * $quotes can be set to 'single' to encode ' to ', 'double' to encode " to + * ", 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,7 +265,7 @@ } /** - * Replaces accents in a string + * Replaces accents in a string. * * {@internal Missing Long Description}} * @@ -404,7 +405,7 @@ } /** - * Filters certain characters from the file name. + * Filters certain characters from the file name. * * {@internal Missing Long Description}} * @@ -426,15 +427,16 @@ } /** - * 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,16 +453,17 @@ } /** - * 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,9 +476,9 @@ } /** - * 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,9 +513,10 @@ } /** - * 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,10 +531,11 @@ } /** - * Converts a number of characters from a string + * Converts a number of characters from a string. * - * Metadata tags <> 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,7 +598,7 @@ } /** - * Fixes javascript bugs in browsers. + * Fixes javascript bugs in browsers. * * {@internal Missing Long Description}} * @@ -751,17 +756,17 @@ } /** - * 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,7 +783,7 @@ * @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,7 +791,7 @@ } /** - * Add leading zeros when necessary + * Add leading zeros when necessary. * * {@internal Missing Long Description}} * @@ -817,15 +822,13 @@ } /** - * 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,11 +841,10 @@ } /** - * 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,7 +944,7 @@ * * {@internal Missing Long Description}} * - * @since 2.5 + * @since 2.5.0 * @access private * * @param unknown_type $matches @@ -967,7 +969,7 @@ * * {@internal Missing Long Description}} * - * @since 2.5 + * @since 2.5.0 * @access private * * @param unknown_type $matches @@ -993,7 +995,7 @@ * * {@internal Missing Long Description}} * - * @since 2.5 + * @since 2.5.0 * @access private * * @param unknown_type $matches @@ -1138,7 +1140,7 @@ } /** - * 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,7 +1158,7 @@ } /** - * 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,7 +1176,7 @@ } /** - * 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,7 +1199,7 @@ } /** - * 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,12 +1231,11 @@ } /** - * 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,7 +1248,7 @@ } /** - * 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,6 +1621,16 @@ 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,7 +1694,7 @@ } /** - * Convert entities, while preserving already-encoded entities + * Convert entities, while preserving already-encoded entities. * * {@internal Missing Long Description}} * @@ -1701,7 +1712,7 @@ } /** - * 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,21 +1728,37 @@ 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,6 +1766,14 @@ 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,11 +1870,28 @@ $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,7 +1899,12 @@ } /** - * 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,8 +1959,10 @@ } /** - * 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,8 +2001,9 @@ /** * 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 & will be counted as 4, < as 3, etc. + * UTF-8, tags and entities safe prefix extraction. Entities inside will *NOT* + * be counted as one character. For example & will be counted as 4, < as + * 3, etc. * * @param integer $str String to get the excerpt from * @param integer $count Maximum number of characters to take @@ -1960,16 +2020,15 @@ /** * 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,14 +2040,12 @@ /** * 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,17 +2059,17 @@ /** * 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,16 +2078,14 @@ $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];