Ticket #5638: 5638.r8783.diff

formatting.php

@@ -154 +154 @@
 /**
  * Checks to see if a string is utf8 encoded.
  *
+ * @author bmorel at ssi dot fr
+ *
  * @since 1.2.1
  *
  * @param string $Str The string to be checked
@@ -211 +213 @@
 }
 
 /**
- * {@internal Missing Short Description}}
+ * Encode the Unicode values to be used in the URI.
  *
- * {@internal Missing Long Description}}
- *
  * @since 1.5.0
  *
- * @param unknown_type $utf8_string
- * @param unknown_type $length
- * @return unknown
+ * @param string $utf8_string
+ * @param int $length Max length of the string
+ * @return string String with Unicode encoded for URI.
  */
 function utf8_uri_encode( $utf8_string, $length = 0 ) {
         $unicode = '';
@@ -263 +263 @@
 }
 
 /**
- * Replaces accents in a string.
+ * Converts all accent characters to ASCII characters.
  *
+ * If there are no accent characters, then the string given is just returned.
+ *
  * @since 1.2.1
  *
- * @param string $string The text to be filtered.
+ * @param string $string Text that might have accent characters
  * @return string Filtered string with replaced "nice" characters.
  */
 function remove_accents($string) {
@@ -403 +405 @@
 /**
  * Filters certain characters from the file name.
  *
- * {@internal Missing Long Description}}
+ * Turns all strings to lowercase removing most characters except alphanumeric
+ * with spaces, dashes and periods. All spaces and underscores are converted to
+ * dashes. Multiple dashes are converted to a single dash. Finally, if the file
+ * name ends with a dash, it is removed.
  *
  * @since 2.1.0
  *
- * @param string $name The string to be sanitized.
- * @return string Sanitized string.
+ * @param string $name The file name
+ * @return string Sanitized file name
  */
 function sanitize_file_name( $name ) { // Like sanitize_title, but with periods
         $name = strtolower( $name );
@@ -426 +431 @@
  *
  * If $strict is true, only alphanumeric characters (as well as _, space, ., -,
  * @) are returned.
+ * Removes tags, octets, entities, and if strict is enabled, will remove all
+ * non-ASCII characters. After sanitizing, it passes the username, raw username
+ * (the username in the parameter), and the strict parameter as parameters for
+ * the filter.
  *
  * @since 2.0.0
+ * @uses apply_filters() Calls 'sanitize_user' hook on username, raw username,
+ *              and $strict parameter.
  *
  * @param string $username The username to be sanitized.
  * @param bool $strict If set limits $username to specific characters. Default false.
@@ -795 +806 @@
  * back '0010'. If you set the number to '4' and the number is '5000', then you
  * will get back '5000'.
  *
+ * Uses sprintf to append the amount of zeros based on the $threshold parameter
+ * and the size of the number. If the number is large enough, then no zeros will
+ * be appended.
+ *
  * @since 0.71
  *
- * @param mixed $number Will convert to string and add zeros
- * @param int $threshold Amount of digits
- * @return string Adds leading zeros to number if needed
+ * @param mixed $number Number to append zeros to if not greater than threshold.
+ * @param int $threshold Digit places number needs to be to not have zeros added.
+ * @return string Adds leading zeros to number if needed.
  */
 function zeroise($number, $threshold) {
         return sprintf('%0'.$threshold.'s', $number);
@@ -907 +922 @@
 }
 
 /**
- * antispambot() - {@internal Missing Short Description}}
+ * Converts email addresses characters to HTML entities to block spam bots.
  *
- * {@internal Missing Long Description}}
- *
  * @since 0.71
  *
- * @param unknown_type $emailaddy
- * @param unknown_type $mailto
- * @return unknown
+ * @param string $emailaddy Email address.
+ * @param int $mailto Optional. Range from 0 to 1. Used for encoding.
+ * @return string Converted email address.
  */
 function antispambot($emailaddy, $mailto=0) {
         $emailNOSPAMaddy = '';
@@ -1028 +1041 @@
 }
 
 /**
- * wp_rel_nofollow() - {@internal Missing Short Description}}
+ * Adds rel nofollow string to all HTML A elements in content.
  *
- * {@internal Missing Long Description}}
- *
  * @since 1.5.0
  *
- * @param unknown_type $text
- * @return unknown
+ * @param string $text Content that may contain HTML A elements.
+ * @return string Converted content.
  */
 function wp_rel_nofollow( $text ) {
         global $wpdb;
@@ -1047 +1058 @@
 }
 
 /**
- * wp_rel_nofollow_callback() - {@internal Missing Short Description}}
+ * Callback to used to add rel=nofollow string to HTML A element.
  *
- * {@internal Missing Long Description}}
+ * Will remove already existing rel="nofollow" and rel='nofollow' from the
+ * string to prevent from invalidating (X)HTML.
  *
  * @since 2.3.0
  *
- * @param unknown_type $matches
- * @return unknown
+ * @param array $matches Single Match
+ * @return string HTML A Element with rel nofollow.
  */
 function wp_rel_nofollow_callback( $matches ) {
         $text = $matches[1];
@@ -1063 +1075 @@
 }
 
 /**
- * convert_smilies() - {@internal Missing Short Description}}
+ * Convert text equivalent of smilies to images.
  *
- * {@internal Missing Long Description}}
+ * Will only convert smilies if the option 'use_smilies' is true and the globals
+ * used in the function aren't empty.
  *
  * @since 0.71
+ * @uses $wp_smiliessearch, $wp_smiliesreplace Smiley replacement arrays.
  *
- * @param string $text
- * @return string
+ * @param string $text Content to convert smilies from text.
+ * @return string Converted content with text smilies replaced with images.
  */
 function convert_smilies($text) {
         global $wp_smiliessearch, $wp_smiliesreplace;
@@ -1115 +1129 @@
 }
 
 /**
- * {@internal Missing Short Description}}
+ * Convert to ASCII from email subjects.
  *
- * {@internal Missing Long Description}}
- *
  * @since 1.2.0
  * @usedby wp_mail() handles charsets in email subjects
  *
- * @param string $string
- * @return string
+ * @param string $string Subject line
+ * @return string Converted string to ASCII
  */
 function wp_iso_descrambler($string) {
         /* this may only work with iso-8859-1, I'm afraid */