diff --git a/wp-admin/includes/post.php b/wp-admin/includes/post.php index 6f6935fac4..8db2a77dd3 100644 --- a/wp-admin/includes/post.php +++ b/wp-admin/includes/post.php @@ -1519,9 +1519,9 @@ function _wp_post_thumbnail_html( $thumbnail_id = null, $post = null ) { * @since 3.5.0 Added the `$post_id` parameter. * @since 4.6.0 Added the `$thumbnail_id` parameter. * - * @param string $content Admin post thumbnail HTML markup. - * @param int $post_id Post ID. - * @param int $thumbnail_id Thumbnail ID. + * @param string $content Admin post thumbnail HTML markup. + * @param int $post_id Post ID. + * @param int|null $thumbnail_id Thumbnail attachment ID, or null if there isn't one. */ return apply_filters( 'admin_post_thumbnail_html', $content, $post->ID, $thumbnail_id ); } diff --git a/wp-includes/class-wp-query.php b/wp-includes/class-wp-query.php index 6a4525a9ee..ddfd6fc7d2 100644 --- a/wp-includes/class-wp-query.php +++ b/wp-includes/class-wp-query.php @@ -1686,14 +1686,14 @@ class WP_Query { } /** - * Retrieve the posts based on query variables. + * Retrieves an array of posts based on query variables. * * There are a few filters and actions that can be used to modify the post * database query. * * @since 1.5.0 * - * @return array List of posts. + * @return WP_Post[]|int[] Array of post objects or post IDs. */ public function get_posts() { global $wpdb; @@ -3357,7 +3357,7 @@ class WP_Query { * @since 1.5.0 * * @param string|array $query URL query string or array of query arguments. - * @return array List of posts. + * @return WP_Post[]|int[] Array of post objects or post IDs. */ public function query( $query ) { $this->init(); diff --git a/wp-includes/class-wp-user.php b/wp-includes/class-wp-user.php index 4d0a28c5cf..fb79242f5f 100644 --- a/wp-includes/class-wp-user.php +++ b/wp-includes/class-wp-user.php @@ -80,7 +80,8 @@ class WP_User { * All capabilities the user has, including individual and role based. * * @since 2.0.0 - * @var array + * @var bool[] Array of key/value pairs where keys represent a capability name and boolean values + * represent whether the user has that capability. */ public $allcaps = array(); @@ -478,16 +479,15 @@ class WP_User { } /** - * Retrieve all of the role capabilities and merge with individual capabilities. + * Retrieves all of the capabilities of the roles of the user, and merges them with individual user capabilities. * - * All of the capabilities of the roles the user belongs to are merged with - * user's individual capabilities. This also means that the user can be denied - * specific capabilities that their role might have, but the user isn't granted - * permission to. + * All of the capabilities of the roles of the user are merged with the user's individual capabilities. This means + * that the user can be denied specific capabilities that their role might have, but the user is specifically denied. * * @since 2.0.0 * - * @return array List of all capabilities for the user. + * @return bool[] Array of key/value pairs where keys represent a capability name and boolean values + * represent whether the user has that capability. */ public function get_role_caps() { $switch_site = false; @@ -751,11 +751,18 @@ class WP_User { * Dynamically filter a user's capabilities. * * @since 2.0.0 - * @since 3.7.0 Added the user object. + * @since 3.7.0 Added the `$user` parameter. * - * @param bool[] $allcaps An array of all the user's capabilities. - * @param string[] $caps Actual capabilities for meta capability. - * @param array $args Optional parameters passed to has_cap(), typically object ID. + * @param bool[] $allcaps Array of key/value pairs where keys represent a capability name and boolean values + * represent whether the user has that capability. + * @param string[] $caps Required primitive capabilities for the requested capability. + * @param array $args { + * Arguments that accompany the requested capability check. + * + * @type string $0 Requested capability. + * @type int $1 Concerned user ID. + * @type mixed ...$2 Optional second and further parameters, typically object ID. + * } * @param WP_User $user The user object. */ $capabilities = apply_filters( 'user_has_cap', $this->allcaps, $caps, $args, $this ); diff --git a/wp-includes/general-template.php b/wp-includes/general-template.php index 81ba70d40b..331d1f21cf 100644 --- a/wp-includes/general-template.php +++ b/wp-includes/general-template.php @@ -2904,11 +2904,11 @@ function wp_site_icon() { } /** - * Filters the site icon meta tags, so Plugins can add their own. + * Filters the site icon meta tags, so plugins can add their own. * * @since 4.3.0 * - * @param array $meta_tags Site Icon meta elements. + * @param string[] $meta_tags Array of Site Icon meta tags. */ $meta_tags = apply_filters( 'site_icon_meta_tags', $meta_tags ); $meta_tags = array_filter( $meta_tags ); diff --git a/wp-includes/js/media-editor.js b/wp-includes/js/media-editor.js index e72bd099ac..fdd0cf78a5 100644 --- a/wp-includes/js/media-editor.js +++ b/wp-includes/js/media-editor.js @@ -609,8 +609,7 @@ return wp.media.view.settings.post.featuredImageId; }, /** - * Set the featured image id, save the post thumbnail data and - * set the HTML in the post meta box to the new featured image. + * Sets the featured image ID property and sets the HTML in the post meta box to the new featured image. * * @param {number} id The post ID of the featured image, or -1 to unset it. */ diff --git a/wp-includes/media.php b/wp-includes/media.php index 33c2e83644..f9dc9c4ebd 100644 --- a/wp-includes/media.php +++ b/wp-includes/media.php @@ -3414,9 +3414,9 @@ function wp_prepare_attachment_for_js( $attachment ) { * * @since 3.5.0 * - * @param array $response Array of prepared attachment data. - * @param WP_Post $attachment Attachment object. - * @param array $meta Array of attachment meta data. + * @param array $response Array of prepared attachment data. + * @param WP_Post $attachment Attachment object. + * @param array|false $meta Array of attachment meta data, or false if there is none. */ return apply_filters( 'wp_prepare_attachment_for_js', $response, $attachment, $meta ); } diff --git a/wp-includes/meta.php b/wp-includes/meta.php index 364c632793..c18ec87340 100644 --- a/wp-includes/meta.php +++ b/wp-includes/meta.php @@ -150,7 +150,8 @@ function add_metadata( $meta_type, $object_id, $meta_key, $meta_value, $unique = * @param mixed $meta_value Metadata value. Must be serializable if non-scalar. * @param mixed $prev_value Optional. If specified, only update existing metadata entries with * the specified value. Otherwise, update all entries. - * @return int|bool Meta ID if the key didn't exist, true on successful update, false on failure. + * @return int|bool The new meta field ID if a field with the given key didn't exist and was + * therefore added, true on successful update, false on failure. */ function update_metadata( $meta_type, $object_id, $meta_key, $meta_value, $prev_value = '' ) { global $wpdb; diff --git a/wp-includes/post.php b/wp-includes/post.php index 3c2b782d4a..7280acb918 100644 --- a/wp-includes/post.php +++ b/wp-includes/post.php @@ -1823,7 +1823,7 @@ function is_post_type_viewable( $post_type ) { } /** - * Retrieve list of latest posts or posts matching criteria. + * Retrieves an array of the latest posts, or posts matching the given criteria. * * The defaults are as follows: * @@ -1844,7 +1844,7 @@ function is_post_type_viewable( $post_type ) { * @type array $exclude An array of post IDs not to retrieve. Default empty array. * @type bool $suppress_filters Whether to suppress filters. Default true. * } - * @return array List of posts. + * @return WP_Post[]|int[] Array of post objects or post IDs. */ function get_posts( $args = null ) { $defaults = array( @@ -1891,7 +1891,7 @@ function get_posts( $args = null ) { // /** - * Add meta data field to a post. + * Adds a meta field to the given post. * * Post meta data is called "Custom Fields" on the Administration Screen. * @@ -1918,11 +1918,11 @@ function add_post_meta( $post_id, $meta_key, $meta_value, $unique = false ) { } /** - * Remove metadata matching criteria from a post. + * Deletes a post meta field for the given post ID. * * You can match based on the key, or key and value. Removing based on key and * value, will keep from removing duplicate metadata with the same key. It also - * allows removing all metadata matching key, if needed. + * allows removing all metadata matching the key, if needed. * * @since 1.5.0 * @@ -1946,17 +1946,16 @@ function delete_post_meta( $post_id, $meta_key, $meta_value = '' ) { } /** - * Retrieve post meta field for a post. + * Retrieves a post meta field for the given post ID. * * @since 1.5.0 * * @param int $post_id Post ID. * @param string $key Optional. The meta key to retrieve. By default, returns * data for all keys. Default empty. - * @param bool $single Optional, default is false. - * If true, return only the first value of the specified meta_key. - * This parameter has no effect if meta_key is not specified. - * @return mixed Will be an array if $single is false. Will be value of meta data + * @param bool $single Optional. If true, returns only the first value for the specified meta key. + * This parameter has no effect if $key is not specified. Default false. + * @return mixed Will be an array if $single is false. Will be value of the meta * field if $single is true. */ function get_post_meta( $post_id, $key = '', $single = false ) { @@ -1964,22 +1963,21 @@ function get_post_meta( $post_id, $key = '', $single = false ) { } /** - * Update post meta field based on post ID. + * Updates a post meta field based on the given post ID. * * Use the $prev_value parameter to differentiate between meta fields with the * same key and post ID. * - * If the meta field for the post does not exist, it will be added. + * If the meta field for the post does not exist, it will be added and its ID returned. * * @since 1.5.0 * * @param int $post_id Post ID. * @param string $meta_key Metadata key. * @param mixed $meta_value Metadata value. Must be serializable if non-scalar. - * @param mixed $prev_value Optional. Previous value to check before removing. - * Default empty. - * @return int|bool Meta ID if the key didn't exist, true on successful update, - * false on failure. + * @param mixed $prev_value Optional. Previous value to check before updating. + * @return int|bool The new meta field ID if a field with the given key didn't exist and was + * therefore added, true on successful update, false on failure. */ function update_post_meta( $post_id, $meta_key, $meta_value, $prev_value = '' ) { // Make sure meta is added to the post, not a revision. @@ -1995,7 +1993,7 @@ function update_post_meta( $post_id, $meta_key, $meta_value, $prev_value = '' ) } /** - * Delete everything from post meta matching meta key. + * Deletes everything from post meta matching the given meta key. * * @since 2.3.0 * @@ -6490,12 +6488,12 @@ function _publish_post_hook( $post_id ) { } /** - * Return the post's parent post ID. + * Returns the ID of the post's parent. * * @since 3.1.0 * * @param int|WP_Post $post Post ID or post object. Defaults to global $post. - * @return int|false Post parent ID, otherwise false. + * @return int|false Post parent ID (which can be 0 if there is no parent), or false if the post does not exist. */ function wp_get_post_parent_id( $post ) { $post = get_post( $post ); @@ -6559,7 +6557,7 @@ function wp_check_post_hierarchy_for_loops( $post_parent, $post_ID ) { } /** - * Set a post thumbnail. + * Sets the post thumbnail (featured image) for the given post. * * @since 3.1.0 * @@ -6581,11 +6579,11 @@ function set_post_thumbnail( $post, $thumbnail_id ) { } /** - * Remove a post thumbnail. + * Removes the thumbnail (featured image) from the given post. * * @since 3.3.0 * - * @param int|WP_Post $post Post ID or post object where thumbnail should be removed from. + * @param int|WP_Post $post Post ID or post object from which the thumbnail should be removed. * @return bool True on success, false on failure. */ function delete_post_thumbnail( $post ) { diff --git a/wp-includes/rest-api/class-wp-rest-response.php b/wp-includes/rest-api/class-wp-rest-response.php index f949cdb9cf..6a88744378 100644 --- a/wp-includes/rest-api/class-wp-rest-response.php +++ b/wp-includes/rest-api/class-wp-rest-response.php @@ -193,7 +193,7 @@ class WP_REST_Response extends WP_HTTP_Response { } /** - * Retrieves the handler that was responsible for generating the response. + * Sets the handler that was responsible for generating the response. * * @since 4.4.0 * diff --git a/wp-includes/rest-api/class-wp-rest-server.php b/wp-includes/rest-api/class-wp-rest-server.php index d18bc5187d..0e71ef966e 100644 --- a/wp-includes/rest-api/class-wp-rest-server.php +++ b/wp-includes/rest-api/class-wp-rest-server.php @@ -904,9 +904,9 @@ class WP_REST_Server { * * @since 4.7.0 * - * @param WP_HTTP_Response $response Result to send to the client. Usually a WP_REST_Response. - * @param WP_REST_Server $handler ResponseHandler instance (usually WP_REST_Server). - * @param WP_REST_Request $request Request used to generate the response. + * @param WP_HTTP_Response|WP_Error $response Result to send to the client. Usually a WP_REST_Response or WP_Error. + * @param array $handler Route handler used for the request. + * @param WP_REST_Request $request Request used to generate the response. */ $response = apply_filters( 'rest_request_before_callbacks', $response, $handler, $request ); @@ -932,7 +932,7 @@ class WP_REST_Server { * @since 4.4.0 * @since 4.5.0 Added `$route` and `$handler` parameters. * - * @param bool $dispatch_result Dispatch result, will be used if not empty. + * @param mixed $dispatch_result Dispatch result, will be used if not empty. * @param WP_REST_Request $request Request used to generate the response. * @param string $route Route matched for the request. * @param array $handler Route handler used for the request. @@ -963,9 +963,9 @@ class WP_REST_Server { * * @since 4.7.0 * - * @param WP_HTTP_Response $response Result to send to the client. Usually a WP_REST_Response. - * @param WP_REST_Server $handler ResponseHandler instance (usually WP_REST_Server). - * @param WP_REST_Request $request Request used to generate the response. + * @param WP_HTTP_Response|WP_Error $response Result to send to the client. Usually a WP_REST_Response or WP_Error. + * @param array $handler Route handler used for the request. + * @param WP_REST_Request $request Request used to generate the response. */ $response = apply_filters( 'rest_request_after_callbacks', $response, $handler, $request ); diff --git a/wp-includes/version.php b/wp-includes/version.php index 642044aa91..2a377bb8dc 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -4,7 +4,7 @@ * * @global string $wp_version */ -$wp_version = '5.0-alpha-43581'; +$wp_version = '5.0-alpha-43582'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.