Docs: Correct and improve various inline documentation.

See #42505

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


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

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 string   $content      Admin post thumbnail HTML markup.
-	 * @param int    $post_id      Post ID.
+	 * @param int      $post_id      Post ID.
-	 * @param int    $thumbnail_id Thumbnail 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 );
 }

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();

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
+	 * All of the capabilities of the roles of the user are merged with the user's individual capabilities. This means
-	 * user's individual capabilities. This also means that the user can be denied
+	 * that the user can be denied specific capabilities that their role might have, but the user is specifically denied.
-	 * specific capabilities that their role might have, but the user isn't granted
-	 * permission to.
 	 *
 	 * @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 bool[]   $allcaps Array of key/value pairs where keys represent a capability name and boolean values
-		 * @param string[] $caps    Actual capabilities for meta capability.
+		 *                          represent whether the user has that capability.
-		 * @param array    $args    Optional parameters passed to has_cap(), typically object ID.
+		 * @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 );

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 );

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
+		 * Sets the featured image ID property and sets the HTML in the post meta box to the new featured image.
-		 * set 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.
 		 */

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 array       $response   Array of prepared attachment data.
-	 * @param WP_Post $attachment Attachment object.
+	 * @param WP_Post     $attachment Attachment object.
-	 * @param array   $meta       Array of attachment meta data.
+	 * @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 );
 }

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;

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.
+ * @param bool   $single  Optional. If true, returns only the first value for the specified meta key.
- *                        If true, return only the first value of the specified meta_key.
+ *                        This parameter has no effect if $key is not specified. Default false.
- *                        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 the meta
- * @return mixed Will be an array if $single is false. Will be value of meta data
  *               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.
+ * @param mixed  $prev_value Optional. Previous value to check before updating.
- *                           Default empty.
+ * @return int|bool The new meta field ID if a field with the given key didn't exist and was
- * @return int|bool Meta ID if the key didn't exist, true on successful update,
+ *                  therefore added, true on successful update, false on failure.
- *                  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 ) {

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
 	 *

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_HTTP_Response|WP_Error $response Result to send to the client. Usually a WP_REST_Response or WP_Error.
-				 * @param WP_REST_Server   $handler  ResponseHandler instance (usually WP_REST_Server).
+				 * @param array                     $handler  Route handler used for the request.
-				 * @param WP_REST_Request  $request  Request used to generate the response.
+				 * @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_HTTP_Response|WP_Error $response Result to send to the client. Usually a WP_REST_Response or WP_Error.
-				 * @param WP_REST_Server   $handler  ResponseHandler instance (usually WP_REST_Server).
+				 * @param array                     $handler  Route handler used for the request.
-				 * @param WP_REST_Request  $request  Request used to generate the response.
+				 * @param WP_REST_Request           $request  Request used to generate the response.
 				 */
 				$response = apply_filters( 'rest_request_after_callbacks', $response, $handler, $request );
 

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.