Docs: Correct and improve various inline documentation.

See #42505


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

src/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 ) {