Docs: Correct and improve inline docs relating to caching, terms, meta, and some misc tweaks.

See #47110   

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


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

wp-admin/includes/media.php

@@ -418,7 +418,7 @@ function media_handle_upload( $file_id, $post_id, $post_data = array(), $overrid
  * @param int    $post_id    The post ID the media is associated with.
  * @param string $desc       Optional. Description of the side-loaded file. Default null.
  * @param array  $post_data  Optional. Post data to override. Default empty array.
- * @return int|object The ID of the attachment or a WP_Error on failure.
+ * @return int|WP_Error The ID of the attachment or a WP_Error on failure.
  */
 function media_handle_sideload( $file_array, $post_id, $desc = null, $post_data = array() ) {
 	$overrides = array( 'test_form' => false );

wp-includes/class-wp-user-query.php

@@ -179,7 +179,7 @@ class WP_User_Query {
 	 *     @type int          $number              Number of users to limit the query for. Can be used in
 	 *                                             conjunction with pagination. Value -1 (all) is supported, but
 	 *                                             should be used with caution on larger sites.
-	 *                                             Default empty (all users).
+	 *                                             Default -1 (all users).
 	 *     @type int          $paged               When used with number, defines the page of results to return.
 	 *                                             Default 1.
 	 *     @type bool         $count_total         Whether to count the total number of users found. If pagination

wp-includes/meta.php

@@ -877,8 +877,8 @@ function delete_metadata_by_mid( $meta_type, $meta_id ) {
  *
  * @global wpdb $wpdb WordPress database abstraction object.
  *
- * @param string    $meta_type  Type of object metadata is for (e.g., comment, post, term, or user).
+ * @param string       $meta_type  Type of object metadata is for (e.g., comment, post, term, or user).
- * @param int|array $object_ids Array or comma delimited list of object IDs to update cache for
+ * @param string|int[] $object_ids Array or comma delimited list of object IDs to update cache for.
  * @return array|false Metadata cache for the specified objects, or false on failure.
  */
 function update_meta_cache( $meta_type, $object_ids ) {
@@ -912,7 +912,7 @@ function update_meta_cache( $meta_type, $object_ids ) {
 	 * @since 5.0.0
 	 *
 	 * @param mixed $check      Whether to allow updating the meta cache of the given type.
-	 * @param array $object_ids Array of object IDs to update the meta cache for.
+	 * @param int[] $object_ids Array of object IDs to update the meta cache for.
 	 */
 	$check = apply_filters( "update_{$meta_type}_metadata_cache", null, $object_ids );
 	if ( null !== $check ) {

wp-includes/post.php

@@ -1266,7 +1266,7 @@ function get_post_types( $args = array(), $output = 'names', $operator = 'and' )
  *                                              If not set, the default is inherited from $public.
  *     @type bool        $show_ui               Whether to generate and allow a UI for managing this post type in the
  *                                              admin. Default is value of $public.
- *     @type bool        $show_in_menu          Where to show the post type in the admin menu. To work, $show_ui
+ *     @type bool|string $show_in_menu          Where to show the post type in the admin menu. To work, $show_ui
  *                                              must be true. If true, the post type is shown in its own top level
  *                                              menu. If false, no menu is shown. If a string of an existing top
  *                                              level menu (eg. 'tools.php' or 'edit.php?post_type=page'), the post
@@ -6416,7 +6416,7 @@ function _get_last_post_time( $timezone, $field, $post_type = 'any' ) {
  *
  * @since 1.5.1
  *
- * @param array $posts Array of post objects (passed by reference).
+ * @param WP_Post[] $posts Array of post objects (passed by reference).
  */
 function update_post_cache( &$posts ) {
 	if ( ! $posts ) {
@@ -6493,10 +6493,10 @@ function clean_post_cache( $post ) {
  *
  * @since 1.5.0
  *
- * @param array  $posts             Array of Post objects
+ * @param WP_Post[] $posts             Array of Post objects
- * @param string $post_type         Optional. Post type. Default 'post'.
+ * @param string    $post_type         Optional. Post type. Default 'post'.
- * @param bool   $update_term_cache Optional. Whether to update the term cache. Default true.
+ * @param bool      $update_term_cache Optional. Whether to update the term cache. Default true.
- * @param bool   $update_meta_cache Optional. Whether to update the meta cache. Default true.
+ * @param bool      $update_meta_cache Optional. Whether to update the meta cache. Default true.
  */
 function update_post_caches( &$posts, $post_type = 'post', $update_term_cache = true, $update_meta_cache = true ) {
 	// No point in doing all this work if we didn't match any posts.
@@ -6548,7 +6548,7 @@ function update_post_caches( &$posts, $post_type = 'post', $update_term_cache =
  *
  * @since 2.1.0
  *
- * @param array $post_ids List of post IDs.
+ * @param int[] $post_ids Array of post IDs.
  * @return array|false Returns false if there is nothing to update or an array
  *                     of metadata.
  */

wp-includes/taxonomy.php

@@ -214,10 +214,10 @@ function get_taxonomies( $args = array(), $output = 'names', $operator = 'and' )
  *
  * @global array $wp_taxonomies The registered taxonomies.
  *
- * @param array|string|WP_Post $object Name of the type of taxonomy object, or an object (row from posts)
+ * @param string|string[]|WP_Post $object Name of the type of taxonomy object, or an object (row from posts)
- * @param string               $output Optional. The type of output to return in the array. Accepts either
+ * @param string                  $output Optional. The type of output to return in the array. Accepts either
- *                                     taxonomy 'names' or 'objects'. Default 'names'.
+ *                                        'names' or 'objects'. Default 'names'.
- * @return array The names of all taxonomy of $object_type.
+ * @return string[]|WP_Taxonomy[] The names or objects of all taxonomies of `$object_type`.
  */
 function get_object_taxonomies( $object, $output = 'names' ) {
 	global $wp_taxonomies;
@@ -1959,11 +1959,11 @@ function wp_delete_category( $cat_ID ) {
  *              'all_with_object_id', an array of `WP_Term` objects will be returned.
  * @since 4.7.0 Refactored to use WP_Term_Query, and to support any WP_Term_Query arguments.
  *
- * @param int|array    $object_ids The ID(s) of the object(s) to retrieve.
+ * @param int|int[]       $object_ids The ID(s) of the object(s) to retrieve.
- * @param string|array $taxonomies The taxonomies to retrieve terms from.
+ * @param string|string[] $taxonomies The taxonomy names to retrieve terms from.
- * @param array|string $args       See WP_Term_Query::__construct() for supported arguments.
+ * @param array|string    $args       See WP_Term_Query::__construct() for supported arguments.
  * @return array|WP_Error The requested term data or empty array if no terms found.
- *                        WP_Error if any of the $taxonomies don't exist.
+ *                        WP_Error if any of the taxonomies don't exist.
  */
 function wp_get_object_terms( $object_ids, $taxonomies, $args = array() ) {
 	if ( empty( $object_ids ) || empty( $taxonomies ) ) {
@@ -1992,10 +1992,10 @@ function wp_get_object_terms( $object_ids, $taxonomies, $args = array() ) {
 	 *
 	 * @since 4.9.0
 	 *
-	 * @param array        $args       An array of arguments for retrieving terms for the given object(s).
+	 * @param array    $args       An array of arguments for retrieving terms for the given object(s).
-	 *                                 See {@see wp_get_object_terms()} for details.
+	 *                             See {@see wp_get_object_terms()} for details.
-	 * @param int|array    $object_ids Object ID or array of IDs.
+	 * @param int[]    $object_ids Array of object IDs.
-	 * @param string|array $taxonomies The taxonomies to retrieve terms from.
+	 * @param string[] $taxonomies Array of taxonomy names to retrieve terms from.
 	 */
 	$args = apply_filters( 'wp_get_object_terms_args', $args, $object_ids, $taxonomies );
 
@@ -2039,11 +2039,11 @@ function wp_get_object_terms( $object_ids, $taxonomies, $args = array() ) {
 	 *
 	 * @since 4.2.0
 	 *
-	 * @param array $terms      An array of terms for the given object or objects.
+	 * @param array    $terms      Array of terms for the given object or objects.
-	 * @param array $object_ids Array of object IDs for which `$terms` were retrieved.
+	 * @param int[]    $object_ids Array of object IDs for which terms were retrieved.
-	 * @param array $taxonomies Array of taxonomies from which `$terms` were retrieved.
+	 * @param string[] $taxonomies Array of taxonomy names from which terms were retrieved.
-	 * @param array $args       An array of arguments for retrieving terms for the given
+	 * @param array    $args       Array of arguments for retrieving terms for the given
-	 *                          object(s). See wp_get_object_terms() for details.
+	 *                             object(s). See wp_get_object_terms() for details.
 	 */
 	$terms = apply_filters( 'get_object_terms', $terms, $object_ids, $taxonomies, $args );
 
@@ -2058,11 +2058,11 @@ function wp_get_object_terms( $object_ids, $taxonomies, $args = array() ) {
 	 *
 	 * @since 2.8.0
 	 *
-	 * @param array     $terms      An array of terms for the given object or objects.
+	 * @param array    $terms      Array of terms for the given object or objects.
-	 * @param int|array $object_ids Object ID or array of IDs.
+	 * @param int[]    $object_ids Array of object IDs for which terms were retrieved.
-	 * @param string    $taxonomies SQL-formatted (comma-separated and quoted) list of taxonomy names.
+	 * @param string[] $taxonomies Array of taxonomy names from which terms were retrieved.
-	 * @param array     $args       An array of arguments for retrieving terms for the given object(s).
+	 * @param array    $args       Array of arguments for retrieving terms for the given
-	 *                              See wp_get_object_terms() for details.
+	 *                             object(s). See wp_get_object_terms() for details.
 	 */
 	return apply_filters( 'wp_get_object_terms', $terms, $object_ids, $taxonomies, $args );
 }
@@ -2421,7 +2421,7 @@ function wp_insert_term( $term, $taxonomy, $args = array() ) {
  *                                    empty value will remove all related terms.
  * @param string           $taxonomy  The context in which to relate the term to the object.
  * @param bool             $append    Optional. If false will delete difference of terms. Default false.
- * @return array|WP_Error Term taxonomy IDs of the affected terms.
+ * @return array|WP_Error Term taxonomy IDs of the affected terms or WP_Error on failure.
  */
 function wp_set_object_terms( $object_id, $terms, $taxonomy, $append = false ) {
 	global $wpdb;
@@ -3365,8 +3365,8 @@ function get_object_term_cache( $id, $taxonomy ) {
  *
  * @since 2.3.0
  *
- * @param string|array $object_ids  Comma-separated list or array of term object IDs.
+ * @param string|int[]    $object_ids  Comma-separated list or array of term object IDs.
- * @param array|string $object_type The taxonomy object type.
+ * @param string|string[] $object_type The taxonomy object type or array of the same.
  * @return void|false False if all of the terms in `$object_ids` are already cached.
  */
 function update_object_term_cache( $object_ids, $object_type ) {

wp-includes/version.php

@@ -13,7 +13,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '5.3-alpha-45914';
+$wp_version = '5.3-alpha-45915';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.