Use `void` instead of `null` where appropriate when pipe-delimiting `@return` types. If a `@return` only contains `void`, remove it.

See #32444.

Built from https://develop.svn.wordpress.org/trunk@32568


git-svn-id: http://core.svn.wordpress.org/trunk@32538 1a063a9b-81f0-0310-95a4-ce76da25c4cd

wp-includes/author-template.php

@@ -70,7 +70,7 @@ function the_author( $deprecated = '', $deprecated_echo = true ) {
  *
  * @since 2.8.0
  *
- * @return string|null The author's display name.
+ * @return string|void The author's display name.
  */
 function get_the_modified_author() {
 	if ( $last_id = get_post_meta( get_post()->ID, '_edit_last', true) ) {
@@ -332,7 +332,7 @@ function get_author_posts_url($author_id, $author_nicename = '') {
  *     @type string $exclude       An array, comma-, or space-separated list of author IDs to exclude. Default empty.
  *     @type string $exclude       An array, comma-, or space-separated list of author IDs to include. Default empty.
  * }
- * @return null|string The output, if echo is set to false. Otherwise null.
+ * @return string|void The output, if echo is set to false.
  */
 function wp_list_authors( $args = '' ) {
 	global $wpdb;

wp-includes/bookmark-template.php

@@ -195,7 +195,7 @@ function _walk_bookmarks( $bookmarks, $args = '' ) {
  *                                      $categorize is true. Accepts 'ASC' (ascending) or 'DESC' (descending).
  *                                      Default 'ASC'.
  * }
- * @return string|null Will only return if echo option is set to not echo. Default is not return anything.
+ * @return string|void Will only return if echo option is set to not echo. Default is not return anything.
  */
 function wp_list_bookmarks( $args = '' ) {
 	$defaults = array(

wp-includes/canonical.php

@@ -36,7 +36,7 @@
  * @param string $requested_url Optional. The URL that was requested, used to
  *		figure if redirect is needed.
  * @param bool $do_redirect Optional. Redirect to the new URL.
- * @return null|string Null, if redirect not needed, or the string of the URL
+ * @return string|void The string of the URL, if redirect needed.
  */
 function redirect_canonical( $requested_url = null, $do_redirect = true ) {
 	global $wp_rewrite, $is_IIS, $wp_query, $wpdb;

wp-includes/capabilities.php

@@ -176,7 +176,7 @@ class WP_Roles {
 	 * @param string $role Role name.
 	 * @param string $display_name Role display name.
 	 * @param array $capabilities List of role capabilities in the above format.
-	 * @return WP_Role|null WP_Role object if role is added, null if already exists.
+	 * @return WP_Role|void WP_Role object, if role is added.
 	 */
 	public function add_role( $role, $display_name, $capabilities = array() ) {
 		if ( isset( $this->roles[$role] ) )

wp-includes/category-template.php

@@ -631,7 +631,7 @@ function wp_list_categories( $args = '' ) {
  * @since 2.3.0
  *
  * @param array|string|null $args Optional. Override default arguments.
- * @return null|array Generated tag cloud, only if no failures and 'array' is set for the 'format' argument.
+ * @return void|array Generated tag cloud, only if no failures and 'array' is set for the 'format' argument.
  *                    Otherwise, this function outputs the tag cloud.
  */
 function wp_tag_cloud( $args = '' ) {
@@ -1405,7 +1405,7 @@ function get_the_term_list( $id, $taxonomy, $before = '', $sep = '', $after = ''
  * @param string $before Optional. Before list.
  * @param string $sep Optional. Separate items using this.
  * @param string $after Optional. After list.
- * @return false|null False on WordPress error. Returns null when displaying.
+ * @return false|void False on WordPress error.
  */
 function the_terms( $id, $taxonomy, $before = '', $sep = ', ', $after = '' ) {
 	$term_list = get_the_term_list( $id, $taxonomy, $before, $sep, $after );

wp-includes/category.php

@@ -99,7 +99,7 @@ function get_category( $category, $output = OBJECT, $filter = 'raw' ) {
  * @param string $category_path URL containing category slugs.
  * @param bool $full_match Optional. Whether full path should be matched.
  * @param string $output Optional. Constant OBJECT, ARRAY_A, or ARRAY_N
- * @return null|object|array|WP_Error Null on failure. Type is based on $output value.
+ * @return object|array|WP_Error|void Type is based on $output value.
  */
 function get_category_by_path( $category_path, $full_match = true, $output = OBJECT ) {
 	$category_path = rawurlencode( urldecode( $category_path ) );

wp-includes/class-wp-admin-bar.php

@@ -14,7 +14,7 @@ class WP_Admin_Bar {
 
 	/**
 	 * @param string $name
-	 * @return string|array|null
+	 * @return string|array|void
 	 */
 	public function __get( $name ) {
 		switch ( $name ) {
@@ -173,7 +173,7 @@ class WP_Admin_Bar {
 
 	/**
 	 * @param string $id
-	 * @return object|null
+	 * @return object|void
 	 */
 	final protected function _get_node( $id ) {
 		if ( $this->bound )
@@ -187,7 +187,7 @@ class WP_Admin_Bar {
 	}
 
 	/**
-	 * @return array|null
+	 * @return array|void
 	 */
 	final public function get_nodes() {
 		if ( ! $nodes = $this->_get_nodes() )
@@ -200,7 +200,7 @@ class WP_Admin_Bar {
 	}
 
 	/**
-	 * @return array|null
+	 * @return array|void
 	 */
 	final protected function _get_nodes() {
 		if ( $this->bound )
@@ -252,7 +252,7 @@ class WP_Admin_Bar {
 	}
 
 	/**
-	 * @return object|null
+	 * @return object|void
 	 */
 	final protected function _bind() {
 		if ( $this->bound )

wp-includes/class-wp-customize-control.php

@@ -1130,7 +1130,7 @@ class WP_Customize_Header_Image_Control extends WP_Customize_Image_Control {
 	}
 
 	/**
-	 * @return string|null
+	 * @return string|void
 	 */
 	public function get_current_image_src() {
 		$src = $this->value();

wp-includes/class-wp-customize-manager.php

@@ -899,7 +899,7 @@ final class WP_Customize_Manager {
 	 * @since 3.4.0
 	 *
 	 * @param string $id Customize Setting ID.
-	 * @return WP_Customize_Setting|null The setting, if set.
+	 * @return WP_Customize_Setting|void The setting, if set.
 	 */
 	public function get_setting( $id ) {
 		if ( isset( $this->settings[ $id ] ) ) {
@@ -944,7 +944,7 @@ final class WP_Customize_Manager {
 	 * @access public
 	 *
 	 * @param string $id Panel ID to get.
-	 * @return WP_Customize_Panel|null Requested panel instance, if set.
+	 * @return WP_Customize_Panel|void Requested panel instance, if set.
 	 */
 	public function get_panel( $id ) {
 		if ( isset( $this->panels[ $id ] ) ) {
@@ -987,7 +987,7 @@ final class WP_Customize_Manager {
 	 * @since 3.4.0
 	 *
 	 * @param string $id Section ID.
-	 * @return WP_Customize_Section|null The section, if set.
+	 * @return WP_Customize_Section|void The section, if set.
 	 */
 	public function get_section( $id ) {
 		if ( isset( $this->sections[ $id ] ) )
@@ -1029,7 +1029,7 @@ final class WP_Customize_Manager {
 	 * @since 3.4.0
 	 *
 	 * @param string $id ID of the control.
-	 * @return WP_Customize_Control|null The control object, if set.
+	 * @return WP_Customize_Control|void The control object, if set.
 	 */
 	public function get_control( $id ) {
 		if ( isset( $this->controls[ $id ] ) )
@@ -1532,13 +1532,13 @@ final class WP_Customize_Manager {
 /**
  * Sanitizes a hex color.
  *
- * Returns either '', a 3 or 6 digit hex color (with #), or null.
+ * Returns either '', a 3 or 6 digit hex color (with #), or nothing.
  * For sanitizing values without a #, see sanitize_hex_color_no_hash().
  *
  * @since 3.4.0
  *
  * @param string $color
- * @return string|null
+ * @return string|void
  */
 function sanitize_hex_color( $color ) {
 	if ( '' === $color )

wp-includes/class-wp-customize-setting.php

@@ -129,7 +129,7 @@ class WP_Customize_Setting {
 	 * @since 4.2.0
 	 * @access public
 	 *
-	 * @return bool|null Returns null if preview() has not been called yet.
+	 * @return bool|void If preview() has been called.
 	 */
 	public function is_current_blog_previewed() {
 		if ( ! isset( $this->_previewed_blog_id ) ) {
@@ -235,7 +235,7 @@ class WP_Customize_Setting {
 	 *
 	 * @since 3.4.0
 	 *
-	 * @return false|null False if cap check fails or value isn't set.
+	 * @return false|void False if cap check fails or value isn't set.
 	 */
 	final public function save() {
 		$value = $this->post_value();
@@ -461,7 +461,7 @@ class WP_Customize_Setting {
 	 * @param $root
 	 * @param $keys
 	 * @param bool $create Default is false.
-	 * @return null|array Keys are 'root', 'node', and 'key'.
+	 * @return array|void Keys are 'root', 'node', and 'key'.
 	 */
 	final protected function multidimensional( &$root, $keys, $create = false ) {
 		if ( $create && empty( $root ) )

wp-includes/class-wp-customize-widgets.php

@@ -109,7 +109,7 @@ final class WP_Customize_Widgets {
 	 * @access protected
 	 *
 	 * @param $setting_id Setting ID.
-	 * @return string|null Setting type. Null otherwise.
+	 * @return string|void Setting type.
 	 */
 	protected function get_setting_type( $setting_id ) {
 		static $cache = array();
@@ -1136,7 +1136,7 @@ final class WP_Customize_Widgets {
 	 * @access public
 	 *
 	 * @param array $value Widget instance to sanitize.
-	 * @return array|null Sanitized widget instance.
+	 * @return array|void Sanitized widget instance.
 	 */
 	public function sanitize_widget_instance( $value ) {
 		if ( $value === array() ) {

wp-includes/class-wp-error.php

@@ -144,7 +144,7 @@ class WP_Error {
 	 * @since 2.1.0
 	 *
 	 * @param string|int $code Optional. Error code.
-	 * @return mixed Null, if no errors.
+	 * @return mixed Error data, if it exists.
 	 */
 	public function get_error_data($code = '') {
 		if ( empty($code) )
@@ -152,7 +152,6 @@ class WP_Error {
 
 		if ( isset($this->error_data[$code]) )
 			return $this->error_data[$code];
-		return null;
 	}
 
 	/**

wp-includes/class-wp-theme.php

@@ -184,7 +184,7 @@ final class WP_Theme implements ArrayAccess {
 	 *
 	 * @param string $theme_dir Directory of the theme within the theme_root.
 	 * @param string $theme_root Theme root.
-	 * @param WP_Error|null $_child If this theme is a parent theme, the child may be passed for validation purposes.
+	 * @param WP_Error|void $_child If this theme is a parent theme, the child may be passed for validation purposes.
 	 */
 	public function __construct( $theme_dir, $theme_root, $_child = null ) {
 		global $wp_theme_directories;

wp-includes/class-wp-xmlrpc-server.php

@@ -291,7 +291,7 @@ class wp_xmlrpc_server extends IXR_Server {
 	 * @since 1.5.2
 	 *
 	 * @param string|array $data Escape single string or array of strings.
-	 * @return string|null Returns with string is passed, alters by-reference
+	 * @return string|void Returns with string is passed, alters by-reference
 	 *                     when array is passed.
 	 */
 	public function escape( &$data ) {

wp-includes/class.wp-scripts.php

@@ -67,7 +67,7 @@ class WP_Scripts extends WP_Dependencies {
 	 *
 	 * @param string $handle
 	 * @param bool   $echo
-	 * @return bool|string|null
+	 * @return bool|string|void
 	 */
 	public function print_scripts_l10n( $handle, $echo = true ) {
 		_deprecated_function( __FUNCTION__, '3.3', 'print_extra_script()' );
@@ -77,7 +77,7 @@ class WP_Scripts extends WP_Dependencies {
 	/**
 	 * @param string $handle
 	 * @param bool   $echo
-	 * @return bool|string|null
+	 * @return bool|string|void
 	 */
 	public function print_extra_script( $handle, $echo = true ) {
 		if ( !$output = $this->get_data( $handle, 'data' ) )

wp-includes/comment-template.php

@@ -388,7 +388,7 @@ function comment_author_url_link( $linktext = '', $before = '', $after = '' ) {
  * @param int|WP_Post  $post_id    Post ID or WP_Post object. Default current post.
  * @param bool         $echo       Optional. Whether to cho or return the output.
  *                                 Default true.
- * @return string|null
+ * @return string|void
  */
 function comment_class( $class = '', $comment_id = null, $post_id = null, $echo = true ) {
 	// Separates classes with a single space, collates classes for comment DIV
@@ -1142,7 +1142,6 @@ function wp_comment_form_unfiltered_html_nonce() {
  * @param string $file              Optional. The file to load. Default '/comments.php'.
  * @param bool   $separate_comments Optional. Whether to separate the comments by comment type.
  *                                  Default false.
- * @return null Returns null if no comments appear.
  */
 function comments_template( $file = '/comments.php', $separate_comments = false ) {
 	global $wp_query, $withcomments, $post, $wpdb, $id, $comment, $user_login, $user_ID, $user_identity, $overridden_cpage;
@@ -1287,7 +1286,6 @@ function comments_popup_script( $width = 400, $height = 400, $file = '' ) {
  * @param string $css_class Optional. CSS class to use for comments. Default empty.
  * @param string $none      Optional. String to display when comments have been turned off.
  *                          Default false.
- * @return null Returns null on single posts and pages.
  */
 function comments_popup_link( $zero = false, $one = false, $more = false, $css_class = '', $none = false ) {
 	global $wpcommentspopupfile, $wpcommentsjavascript;
@@ -1386,7 +1384,7 @@ function comments_popup_link( $zero = false, $one = false, $more = false, $css_c
  * @param int         $comment Comment being replied to. Default current comment.
  * @param int|WP_Post $post    Post ID or WP_Post object the comment is going to be displayed on.
  *                             Default current post.
- * @return null|false|string Link to show comment form, if successful. False, if comments are closed.
+ * @return void|false|string Link to show comment form, if successful. False, if comments are closed.
  */
 function get_comment_reply_link( $args = array(), $comment = null, $post = null ) {
 	$defaults = array(
@@ -1789,10 +1787,8 @@ class Walker_Comment extends Walker {
 	 * @param int    $depth             Depth of current element.
 	 * @param array  $args              An array of arguments.
 	 * @param string $output            Passed by reference. Used to append additional content.
-	 * @return null Null on failure with no changes to parameters.
 	 */
 	public function display_element( $element, &$children_elements, $max_depth, $depth, $args, &$output ) {
-
 		if ( !$element )
 			return;
 

wp-includes/version.php

@@ -4,7 +4,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '4.3-alpha-32567';
+$wp_version = '4.3-alpha-32568';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.