Changeset 48444

Timestamp:

07/12/2020 01:11:35 AM (4 years ago)

Author:

SergeyBiryukov

Message:

Docs: Improve documentation for sanitize_user(), sanitize_title(), sanitize_title_with_dashes().

See #49572.

File:

• trunk/src/wp-includes/formatting.php (modified) (5 diffs)

trunk/src/wp-includes/formatting.php

@@ -2085 +2085 @@
  *
  * @param string $username The username to be sanitized.
- * @param bool   $strict   If set limits $username to specific characters. Default false.
+ * @param bool   $strict   Optional. If set limits $username to specific characters.
+ *                         Default false.
  * @return string The sanitized username, after passing through filters.
  */
@@ -2113 +2114 @@
      * @param string $username     Sanitized username.
      * @param string $raw_username The username prior to sanitization.
-     * @param bool   $strict       Whether to limit the sanitization to specific characters. Default false.
+     * @param bool   $strict       Whether to limit the sanitization to specific characters.
      */
     return apply_filters( 'sanitize_user', $username, $raw_username, $strict );
@@ -2121 +2122 @@
  * Sanitizes a string key.
  *
- * Keys are used as internal identifiers. Lowercase alphanumeric characters, dashes and underscores are allowed.
+ * Keys are used as internal identifiers. Lowercase alphanumeric characters,
+ * dashes, and underscores are allowed.
  *
  * @since 3.0.0
@@ -2145 +2147 @@
 
 /**
- * Sanitizes a string into a slug, which can be used in places such as URLs or HTML attributes.
- *
- * In a save context, converts accents to ASCII characters. By default, output is
- * further limited to alphanumeric characters, underscore (_) and dash (-) through the
- * 'sanitize_title' filter. If $title is empty and $fallback_title is set, the latter
- * will be used.
+ * Sanitizes a string into a slug, which can be used in URLs or HTML attributes.
+ *
+ * By default, converts accent characters to ASCII characters and further
+ * limits the output to alphanumeric characters, underscore (_) and dash (-)
+ * through the {@see 'sanitize_title'} filter.
+ *
+ * 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.
- * @param string $context        Optional. The operation for which the string is sanitized
+ * @param string $fallback_title Optional. A title to use if $title is empty. Default empty.
+ * @param string $context        Optional. The operation for which the string is sanitized.
+ *                               Default 'save'.
  * @return string The sanitized string.
  */
@@ -2207 +2211 @@
  *
  * @param string $title     The title to be sanitized.
- * @param string $raw_title Optional. Not used.
+ * @param string $raw_title Optional. Not used. Default empty.
  * @param string $context   Optional. The operation for which the string is sanitized.
+ *                          Default 'display'.
  * @return string The sanitized title.
  */