<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head><meta http-equiv="content-type" content="text/html; charset=utf-8" />
<title>[23365] trunk/wp-includes/formatting.php: PHPDoc fixes and additions.</title>
</head>
<body>
<style type="text/css"><!--
#msg dl.meta { border: 1px #006 solid; background: #369; padding: 6px; color: #fff; }
#msg dl.meta dt { float: left; width: 6em; font-weight: bold; }
#msg dt:after { content:':';}
#msg dl, #msg dt, #msg ul, #msg li, #header, #footer, #logmsg { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; }
#msg dl a { font-weight: bold}
#msg dl a:link { color:#fc3; }
#msg dl a:active { color:#ff0; }
#msg dl a:visited { color:#cc6; }
h3 { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; font-weight: bold; }
#msg pre { overflow: auto; background: #ffc; border: 1px #fa0 solid; padding: 6px; }
#logmsg { background: #ffc; border: 1px #fa0 solid; padding: 1em 1em 0 1em; }
#logmsg p, #logmsg pre, #logmsg blockquote { margin: 0 0 1em 0; }
#logmsg p, #logmsg li, #logmsg dt, #logmsg dd { line-height: 14pt; }
#logmsg h1, #logmsg h2, #logmsg h3, #logmsg h4, #logmsg h5, #logmsg h6 { margin: .5em 0; }
#logmsg h1:first-child, #logmsg h2:first-child, #logmsg h3:first-child, #logmsg h4:first-child, #logmsg h5:first-child, #logmsg h6:first-child { margin-top: 0; }
#logmsg ul, #logmsg ol { padding: 0; list-style-position: inside; margin: 0 0 0 1em; }
#logmsg > ul, #logmsg > ol { margin-left: 0; margin: 0 0 1em 0; }
#logmsg pre { background: #eee; padding: 1em; }
#logmsg blockquote { border: 1px solid #fa0; border-left-width: 10px; padding: 1em 1em 0 1em; background: white;}
#logmsg dl { margin: 0; }
#logmsg dt { font-weight: bold; }
#logmsg dd { margin: 0; padding: 0 0 0.5em 0; }
#logmsg dd:before { content:'\00bb';}
#logmsg table { border-spacing: 0px; border-collapse: collapse; border-top: 4px solid #fa0; border-bottom: 1px solid #fa0; background: #fff; }
#logmsg table th { text-align: left; font-weight: normal; padding: 0.2em 0.5em; border-top: 1px dotted #fa0; }
#logmsg table td { text-align: right; border-top: 1px dotted #fa0; padding: 0.2em 0.5em; }
#logmsg table thead th { text-align: center; border-bottom: 1px solid #fa0; }
#logmsg table th.Corner { text-align: left; }
#logmsg hr { border: none 0; border-top: 2px dashed #fa0; height: 1px; }
#header, #footer { color: #fff; background: #636; border: 1px #300 solid; padding: 6px; }
#patch { width: 100%; }
#patch h4 {font-family: verdana,arial,helvetica,sans-serif;font-size:10pt;padding:8px;background:#369;color:#fff;margin:0;}
#patch .propset h4, #patch .binary h4 {margin:0;}
#patch pre {padding:0;line-height:1.2em;margin:0;}
#patch .diff {width:100%;background:#eee;padding: 0 0 10px 0;overflow:auto;}
#patch .propset .diff, #patch .binary .diff {padding:10px 0;}
#patch span {display:block;padding:0 10px;}
#patch .modfile, #patch .addfile, #patch .delfile, #patch .propset, #patch .binary, #patch .copfile {border:1px solid #ccc;margin:10px 0;}
#patch ins {background:#dfd;text-decoration:none;display:block;padding:0 10px;}
#patch del {background:#fdd;text-decoration:none;display:block;padding:0 10px;}
#patch .lines, .info {color:#888;background:#fff;}
--></style>
<div id="msg">
<dl class="meta">
<dt>Revision</dt> <dd><a href="http://core.trac.wordpress.org/changeset/23365">23365</a></dd>
<dt>Author</dt> <dd>SergeyBiryukov</dd>
<dt>Date</dt> <dd>2013-02-01 18:07:08 +0000 (Fri, 01 Feb 2013)</dd>
</dl>
<h3>Log Message</h3>
<pre>PHPDoc fixes and additions. props bananastalktome, DrewAPicture. fixes <a href="http://core.trac.wordpress.org/ticket/23313">#23313</a>.</pre>
<h3>Modified Paths</h3>
<ul>
<li><a href="#trunkwpincludesformattingphp">trunk/wp-includes/formatting.php</a></li>
</ul>
</div>
<div id="patch">
<h3>Diff</h3>
<a id="trunkwpincludesformattingphp"></a>
<div class="modfile"><h4>Modified: trunk/wp-includes/formatting.php (23364 => 23365)</h4>
<pre class="diff"><span>
<span class="info">--- trunk/wp-includes/formatting.php 2013-02-01 01:50:19 UTC (rev 23364)
+++ trunk/wp-includes/formatting.php 2013-02-01 18:07:08 UTC (rev 23365)
</span><span class="lines">@@ -5,7 +5,7 @@
</span><span class="cx"> * Handles many functions for formatting output.
</span><span class="cx"> *
</span><span class="cx"> * @package WordPress
</span><del>- **/
</del><ins>+ */
</ins><span class="cx">
</span><span class="cx"> /**
</span><span class="cx"> * Replaces common plain text characters into formatted entities
</span><span class="lines">@@ -134,8 +134,8 @@
</span><span class="cx"> * Search for disabled element tags. Push element to stack on tag open and pop
</span><span class="cx"> * on tag close. Assumes first character of $text is tag opening.
</span><span class="cx"> *
</span><ins>+ * @since 2.9.0
</ins><span class="cx"> * @access private
</span><del>- * @since 2.9.0
</del><span class="cx"> *
</span><span class="cx"> * @param string $text Text to check. First character is assumed to be $opening
</span><span class="cx"> * @param array $stack Array used as stack of opened tag elements
</span><span class="lines">@@ -262,6 +262,7 @@
</span><span class="cx"> *
</span><span class="cx"> * @since 3.1.0
</span><span class="cx"> * @access private
</span><ins>+ *
</ins><span class="cx"> * @param array $matches preg_replace_callback matches array
</span><span class="cx"> * @return string
</span><span class="cx"> */
</span><span class="lines">@@ -363,6 +364,7 @@
</span><span class="cx"> * &quot;, or ENT_QUOTES to do both. Default is ENT_NOQUOTES where no quotes are encoded.
</span><span class="cx"> *
</span><span class="cx"> * @since 1.2.2
</span><ins>+ * @access private
</ins><span class="cx"> *
</span><span class="cx"> * @param string $string The text which is to be encoded.
</span><span class="cx"> * @param mixed $quote_style Optional. Converts double quotes if set to ENT_COMPAT, both single and double if set to ENT_QUOTES or none if set to ENT_NOQUOTES. Also compatible with old values; converting single quotes if set to 'single', double if set to 'double' or both if otherwise set. Default is ENT_NOQUOTES.
</span><span class="lines">@@ -442,7 +444,7 @@
</span><span class="cx"> * $quote_style can be set to ENT_COMPAT to decode " entities,
</span><span class="cx"> * or ENT_QUOTES to do both " and '. Default is ENT_NOQUOTES where no quotes are decoded.
</span><span class="cx"> *
</span><del>- * @since 2.8
</del><ins>+ * @since 2.8.0
</ins><span class="cx"> *
</span><span class="cx"> * @param string $string The text which is to be decoded.
</span><span class="cx"> * @param mixed $quote_style Optional. Converts double quotes if set to ENT_COMPAT, both single and double if set to ENT_QUOTES or none if set to ENT_NOQUOTES. Also compatible with old _wp_specialchars() values; converting single quotes if set to 'single', double if set to 'double' or both if otherwise set. Default is ENT_NOQUOTES.
</span><span class="lines">@@ -499,7 +501,7 @@
</span><span class="cx"> /**
</span><span class="cx"> * Checks for invalid UTF8 in a string.
</span><span class="cx"> *
</span><del>- * @since 2.8
</del><ins>+ * @since 2.8.0
</ins><span class="cx"> *
</span><span class="cx"> * @param string $string The text which is to be checked.
</span><span class="cx"> * @param boolean $strip Optional. Whether to attempt to strip out invalid UTF8. Default is false.
</span><span class="lines">@@ -824,12 +826,12 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Sanitizes a filename replacing whitespace with dashes
</del><ins>+ * Sanitizes a filename, replacing whitespace with dashes.
</ins><span class="cx"> *
</span><span class="cx"> * Removes special characters that are illegal in filenames on certain
</span><span class="cx"> * operating systems and special characters requiring special escaping
</span><span class="cx"> * to manipulate at the command line. Replaces spaces and consecutive
</span><del>- * dashes with a single dash. Trim period, dash and underscore from beginning
</del><ins>+ * dashes with a single dash. Trims period, dash and underscore from beginning
</ins><span class="cx"> * and end of filename.
</span><span class="cx"> *
</span><span class="cx"> * @since 2.1.0
</span><span class="lines">@@ -881,7 +883,7 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Sanitize username stripping out unsafe characters.
</del><ins>+ * Sanitizes a username, stripping out unsafe characters.
</ins><span class="cx"> *
</span><span class="cx"> * Removes tags, octets, entities, and if strict is enabled, will only keep
</span><span class="cx"> * alphanumeric, _, space, ., -, @. After sanitizing, it passes the username,
</span><span class="lines">@@ -916,7 +918,7 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Sanitize a string key.
</del><ins>+ * Sanitizes a string key.
</ins><span class="cx"> *
</span><span class="cx"> * Keys are used as internal identifiers. Lowercase alphanumeric characters, dashes and underscores are allowed.
</span><span class="cx"> *
</span><span class="lines">@@ -933,7 +935,7 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Sanitizes title or use fallback title.
</del><ins>+ * Sanitizes a title, or returns a fallback title.
</ins><span class="cx"> *
</span><span class="cx"> * Specifically, HTML and PHP tags are stripped. Further actions can be added
</span><span class="cx"> * via the plugin API. If $title is empty and $fallback_title is set, the latter
</span><span class="lines">@@ -946,7 +948,7 @@
</span><span class="cx"> * @param string $context Optional. The operation for which the string is sanitized
</span><span class="cx"> * @return string The sanitized string.
</span><span class="cx"> */
</span><del>-function sanitize_title($title, $fallback_title = '', $context = 'save') {
</del><ins>+function sanitize_title( $title, $fallback_title = '', $context = 'save' ) {
</ins><span class="cx"> $raw_title = $title;
</span><span class="cx">
</span><span class="cx"> if ( 'save' == $context )
</span><span class="lines">@@ -960,12 +962,23 @@
</span><span class="cx"> return $title;
</span><span class="cx"> }
</span><span class="cx">
</span><del>-function sanitize_title_for_query($title) {
- return sanitize_title($title, '', 'query');
</del><ins>+/**
+ * Sanitizes a title with the 'query' context.
+ *
+ * Used for querying the database for a value from URL.
+ *
+ * @since 3.1.0
+ * @uses sanitize_title()
+ *
+ * @param string $title The string to be sanitized.
+ * @return string The sanitized string.
+ */
+function sanitize_title_for_query( $title ) {
+ return sanitize_title( $title, '', 'query' );
</ins><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Sanitizes title, replacing whitespace and a few other characters with dashes.
</del><ins>+ * Sanitizes a title, replacing whitespace and a few other characters with dashes.
</ins><span class="cx"> *
</span><span class="cx"> * Limits the output to alphanumeric characters, underscore (_) and dash (-).
</span><span class="cx"> * Whitespace becomes a dash.
</span><span class="lines">@@ -977,7 +990,7 @@
</span><span class="cx"> * @param string $context Optional. The operation for which the string is sanitized.
</span><span class="cx"> * @return string The sanitized title.
</span><span class="cx"> */
</span><del>-function sanitize_title_with_dashes($title, $raw_title = '', $context = 'display') {
</del><ins>+function sanitize_title_with_dashes( $title, $raw_title = '', $context = 'display' ) {
</ins><span class="cx"> $title = strip_tags($title);
</span><span class="cx"> // Preserve escaped octets.
</span><span class="cx"> $title = preg_replace('|%([a-fA-F0-9][a-fA-F0-9])|', '---$1---', $title);
</span><span class="lines">@@ -1049,7 +1062,7 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Sanitizes a html classname to ensure it only contains valid characters
</del><ins>+ * Sanitizes an HTML classname to ensure it only contains valid characters.
</ins><span class="cx"> *
</span><span class="cx"> * Strips the string down to A-Z,a-z,0-9,_,-. If this results in an empty
</span><span class="cx"> * string then it will return the alternative value supplied.
</span><span class="lines">@@ -1883,6 +1896,7 @@
</span><span class="cx"> *
</span><span class="cx"> * @since 3.1.0
</span><span class="cx"> * @access private
</span><ins>+ *
</ins><span class="cx"> * @param array $match The preg_replace_callback matches array
</span><span class="cx"> * @return array Converted chars
</span><span class="cx"> */
</span><span class="lines">@@ -2705,7 +2719,7 @@
</span><span class="cx"> /**
</span><span class="cx"> * Escaping for textarea values.
</span><span class="cx"> *
</span><del>- * @since 3.1
</del><ins>+ * @since 3.1.0
</ins><span class="cx"> *
</span><span class="cx"> * @param string $text
</span><span class="cx"> * @return string
</span><span class="lines">@@ -2716,7 +2730,7 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Escape a HTML tag name.
</del><ins>+ * Escape an HTML tag name.
</ins><span class="cx"> *
</span><span class="cx"> * @since 2.5.0
</span><span class="cx"> *
</span><span class="lines">@@ -3189,10 +3203,17 @@
</span><span class="cx"> return '<' . $tag . $link . ' target="' . esc_attr( $_links_add_target ) . '">';
</span><span class="cx"> }
</span><span class="cx">
</span><del>-// normalize EOL characters and strip duplicate whitespace
</del><ins>+/**
+ * Normalize EOL characters and strip duplicate whitespace.
+ *
+ * @since 2.7.0
+ *
+ * @param string $str The string to normalize.
+ * @return string The normalized string.
+ */
</ins><span class="cx"> function normalize_whitespace( $str ) {
</span><del>- $str = trim($str);
- $str = str_replace("\r", "\n", $str);
</del><ins>+ $str = trim( $str );
+ $str = str_replace( "\r", "\n", $str );
</ins><span class="cx"> $str = preg_replace( array( '/\n+/', '/[ \t]+/' ), array( "\n", ' ' ), $str );
</span><span class="cx"> return $str;
</span><span class="cx"> }
</span></span></pre>
</div>
</div>
</body>
</html>