Docs: Miscellaneous DocBlock corrections.

See #49572.

git-svn-id: https://develop.svn.wordpress.org/trunk@47892 602fd350-edb4-49c9-b593-d223f7449a82

src/wp-includes/kses.php

@@ -2305,11 +2305,13 @@ function safecss_filter_attr( $css, $deprecated = '' ) {
 			/**
 			 * Filters the regex limiting the list of characters not allowed in CSS rules.
 			 *
-			 * Default behaviour is to remove any css containing \ ( & } = or comments, except for url() usage.
+			 * Default behaviour is to remove any CSS containing \ ( & } = or comments,
+			 * except for url() usage.
 			 *
 			 * @since 5.5.0
 			 *
-			 * @param string $regex           Regex pattern of disallowed characters in CSS rules. Default is '%[\\\(&=}]|/\*%'.
+			 * @param string $regex           Regex pattern of disallowed characters in CSS rules.
+			 *                                Default is '%[\\\(&=}]|/\*%'.
 			 * @param string $css_test_string CSS value to test.
 			 */
 			$disallowed_chars = apply_filters( 'safe_style_disallowed_chars', '%[\\\(&=}]|/\*%', $css_test_string );

src/wp-includes/link-template.php

@@ -3862,10 +3862,10 @@ function wp_get_shortlink( $id = 0, $context = 'post', $allow_slugs = true ) {
 	 *
 	 * @since 3.0.0
 	 *
-	 * @param bool|string $return      Short-circuit return value. Either false or a URL string.
-	 * @param int         $id          Post ID, or 0 for the current post.
-	 * @param string      $context     The context for the link. One of 'post' or 'query',
-	 * @param bool        $allow_slugs Whether to allow post slugs in the shortlink.
+	 * @param false|string $return      Short-circuit return value. Either false or a URL string.
+	 * @param int          $id          Post ID, or 0 for the current post.
+	 * @param string       $context     The context for the link. One of 'post' or 'query',
+	 * @param bool         $allow_slugs Whether to allow post slugs in the shortlink.
 	 */
 	$shortlink = apply_filters( 'pre_get_shortlink', false, $id, $context, $allow_slugs );
 

src/wp-includes/ms-deprecated.php

@@ -165,7 +165,7 @@ function is_main_blog() {
  *
  * @param string $email        Email address to verify.
  * @param bool   $check_domain Deprecated.
- * @return string|bool Either false or the valid email address.
+ * @return string|false Valid email address on success, false on failure.
  */
 function validate_email( $email, $check_domain = true) {
 	_deprecated_function( __FUNCTION__, '3.0.0', 'is_email()' );

src/wp-includes/ms-functions.php

@@ -392,7 +392,7 @@ function get_blog_id_from_url( $domain, $path = '/' ) {
  * @since MU (3.0.0)
  *
  * @param string $user_email The email provided by the user at registration.
- * @return bool Returns true when the email address is banned.
+ * @return bool True when the email address is banned, false otherwise.
  */
 function is_email_address_unsafe( $user_email ) {
 	$banned_names = get_site_option( 'banned_email_domains' );

src/wp-includes/nav-menu-template.php

@@ -91,7 +91,7 @@ function wp_nav_menu( $args = array() ) {
 	/**
 	 * Filters whether to short-circuit the wp_nav_menu() output.
 	 *
-	 * Returning a non-null value to the filter will short-circuit
+	 * Passing a non-null value to the filter will short-circuit
 	 * wp_nav_menu(), echoing that value if $args->echo is true,
 	 * returning that value otherwise.
 	 *

src/wp-includes/post.php

@@ -3681,7 +3681,7 @@ function wp_insert_post( $postarr, $wp_error = false ) {
 	 * 1. The post type supports the title, editor, and excerpt fields
 	 * 2. The title, editor, and excerpt fields are all empty
 	 *
-	 * Returning a truthy value to the filter will effectively short-circuit
+	 * Passing a truthy value to the filter will effectively short-circuit
 	 * the new post being inserted, returning 0. If $wp_error is true, a WP_Error
 	 * will be returned instead.
 	 *