Changeset 43582 for trunk/src/wp-includes/post.php

Timestamp:

08/27/2018 02:27:22 PM (6 years ago)

Author:

johnbillion

Message:

Docs: Correct and improve various inline documentation.

See #42505

File:

• trunk/src/wp-includes/post.php (modified) (12 diffs)

trunk/src/wp-includes/post.php

@@ -1824 +1824 @@
 
 /**
- * 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:
@@ -1845 +1845 @@
  *     @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 ) {
@@ -1892 +1892 @@
 
 /**
- * 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.
@@ -1919 +1919 @@
 
 /**
- * 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
@@ -1947 +1947 @@
 
 /**
- * Retrieve post meta field for a post.
+ * Retrieves a post meta field for the given post ID.
  *
  * @since 1.5.0
@@ -1954 +1954 @@
  * @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.
  */
@@ -1965 +1964 @@
 
 /**
- * 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
@@ -1977 +1976 @@
  * @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 = '' ) {
@@ -1996 +1994 @@
 
 /**
- * Delete everything from post meta matching meta key.
+ * Deletes everything from post meta matching the given meta key.
  *
  * @since 2.3.0
@@ -6491 +6489 @@
 
 /**
- * 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 ) {
@@ -6560 +6558 @@
 
 /**
- * Set a post thumbnail.
+ * Sets the post thumbnail (featured image) for the given post.
  *
  * @since 3.1.0
@@ -6582 +6580 @@
 
 /**
- * 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.
  */