From 5fde82be764c0a2d206ea203641fadb491295b8b Mon Sep 17 00:00:00 2001
From: Drew Jaynes <drewapicture@git.wordpress.org>
Date: Sat, 8 Mar 2014 19:31:51 +0000
Subject: [PATCH] Better standardize parameter value types in PHPDocs where
 both a post ID or `WP_Post` would be acceptable.

Covers cases where previously only `int` or `int|object` types were notated.

Props coffee2code for the original patch.
See #20495.


git-svn-id: https://develop.svn.wordpress.org/trunk@27473 602fd350-edb4-49c9-b593-d223f7449a82
---
 src/wp-includes/post-template.php | 20 ++++++++++----------
 src/wp-includes/post.php          | 26 +++++++++++++-------------
 src/wp-includes/taxonomy.php      |  4 ++--
 3 files changed, 25 insertions(+), 25 deletions(-)

diff --git a/src/wp-includes/post-template.php b/src/wp-includes/post-template.php
index 3d7daf3404..fcc75f934e 100644
--- a/src/wp-includes/post-template.php
+++ b/src/wp-includes/post-template.php
@@ -96,7 +96,7 @@ function the_title_attribute( $args = '' ) {
  *
  * @since 0.71
  *
- * @param int|object $post Optional. Post ID or object.
+ * @param int|WP_Post $post Optional. Post ID or post object.
  * @return string
  */
 function get_the_title( $post = 0 ) {
@@ -129,7 +129,7 @@ function get_the_title( $post = 0 ) {
  *
  * @since 1.5.0
  *
- * @param int $id Optional. Post ID.
+ * @param int|WP_Post $id Optional. Post ID or post object.
  */
 function the_guid( $id = 0 ) {
 	echo esc_url( get_the_guid( $id ) );
@@ -144,7 +144,7 @@ function the_guid( $id = 0 ) {
  *
  * @since 1.5.0
  *
- * @param int $id Optional. Post ID.
+ * @param int|WP_Post $id Optional. Post ID or post object.
  * @return string
  */
 function get_the_guid( $id = 0 ) {
@@ -280,7 +280,7 @@ function get_the_excerpt( $deprecated = '' ) {
  *
  * @since 2.3.0
  *
- * @param int $id Optional. Post ID.
+ * @param int|WP_Post $id Optional. Post ID or post object.
  * @return bool
  */
 function has_excerpt( $id = 0 ) {
@@ -294,7 +294,7 @@ function has_excerpt( $id = 0 ) {
  * @since 2.7.0
  *
  * @param string|array $class One or more classes to add to the class list.
- * @param int $post_id An optional post ID.
+ * @param int|WP_Post $post_id Optional. Post ID or post object.
  */
 function post_class( $class = '', $post_id = null ) {
 	// Separates classes with a single space, collates classes for post DIV
@@ -316,7 +316,7 @@ function post_class( $class = '', $post_id = null ) {
  * @since 2.7.0
  *
  * @param string|array $class One or more classes to add to the class list.
- * @param int $post_id An optional post ID.
+ * @param int|WP_Post $post_id Optional. Post ID or post object.
  * @return array Array of classes.
  */
 function get_post_class( $class = '', $post_id = null ) {
@@ -1173,7 +1173,7 @@ class Walker_PageDropdown extends Walker {
  *
  * @since 2.0.0
  *
- * @param int $id Optional. Post ID.
+ * @param int|WP_Post $id Optional. Post ID or post object.
  * @param bool $fullsize Optional, default is false. Whether to use full size.
  * @param bool $deprecated Deprecated. Not used.
  * @param bool $permalink Optional, default is false. Whether to include permalink.
@@ -1194,7 +1194,7 @@ function the_attachment_link( $id = 0, $fullsize = false, $deprecated = false, $
  * @since 2.5.0
  * @uses apply_filters() Calls 'wp_get_attachment_link' filter on HTML content with same parameters as function.
  *
- * @param int $id Optional. Post ID.
+ * @param int|WP_Post $id Optional. Post ID or post object.
  * @param string $size Optional, default is 'thumbnail'. Size of image, either array or string.
  * @param bool $permalink Optional, default is false. Whether to add permalink to image.
  * @param bool $icon Optional, default is false. Whether to include icon.
@@ -1259,7 +1259,7 @@ function prepend_attachment($content) {
  *
  * @since 1.0.0
  * @uses apply_filters() Calls 'the_password_form' filter on output.
- * @param int|WP_Post $post Optional. A post id or post object. Defaults to the current post when in The Loop, undefined otherwise.
+ * @param int|WP_Post $post Optional. A post ID or post object.
  * @return string HTML content for password form for password protected post.
  */
 function get_the_password_form( $post = 0 ) {
@@ -1420,7 +1420,7 @@ function wp_post_revision_title_expanded( $revision, $link = true ) {
  * @uses get_edit_post_link()
  * @uses get_the_author_meta()
  *
- * @param int|object $post_id Post ID or post object.
+ * @param int|WP_Post $post_id Optional. Post ID or post object.
  * @param string $type 'all' (default), 'revision' or 'autosave'
  * @return null
  */
diff --git a/src/wp-includes/post.php b/src/wp-includes/post.php
index 14c02d3a4a..9240e55d28 100644
--- a/src/wp-includes/post.php
+++ b/src/wp-includes/post.php
@@ -380,7 +380,7 @@ function get_extended($post) {
  * @since 1.5.1
  * @link http://codex.wordpress.org/Function_Reference/get_post
  *
- * @param int|object $post Post ID or post object. Optional, default is the current post from the loop.
+ * @param int|WP_Post $post Optional. Post ID or post object.
  * @param string $output Optional, default is Object. Either OBJECT, ARRAY_A, or ARRAY_N.
  * @param string $filter Optional, default is raw.
  * @return WP_Post|null WP_Post on success or null on failure
@@ -710,7 +710,7 @@ final class WP_Post {
  *
  * @since 2.5.0
  *
- * @param int|object $post Post ID or post object
+ * @param int|WP_Post $post Post ID or post object.
  * @return array Ancestor IDs or empty array if none are found.
  */
 function get_post_ancestors( $post ) {
@@ -747,7 +747,7 @@ function get_post_ancestors( $post ) {
  * @uses sanitize_post_field() See for possible $context values.
  *
  * @param string $field Post field name.
- * @param int|object $post Post ID or post object.
+ * @param int|WP_Post $post Post ID or post object.
  * @param string $context Optional. How to filter the field. Default is 'display'.
  * @return string The value of the post field on success, empty string on failure.
  */
@@ -771,7 +771,7 @@ function get_post_field( $field, $post, $context = 'display' ) {
  *
  * @since 2.0.0
  *
- * @param int $ID Optional. Post ID. Default is the current post from the loop.
+ * @param int|WP_Post $ID Optional. Post ID or post object.
  * @return string|bool The mime type on success, false on failure.
  */
 function get_post_mime_type($ID = '') {
@@ -791,7 +791,7 @@ function get_post_mime_type($ID = '') {
  *
  * @since 2.0.0
  *
- * @param int $ID Optional. Post ID. Default is the current post from the loop.
+ * @param int|WP_Post $ID Optional. Post ID or post object.
  * @return string|bool Post status on success, false on failure.
  */
 function get_post_status($ID = '') {
@@ -1025,7 +1025,7 @@ function post_type_exists( $post_type ) {
  *
  * @since 2.1.0
  *
- * @param int|object $post Optional. Post ID or post object. Default is the current post from the loop.
+ * @param int|WP_Post $post Optional. Post ID or post object.
  * @return string|bool Post type on success, false on failure.
  */
 function get_post_type( $post = null ) {
@@ -2480,7 +2480,7 @@ function wp_untrash_post($post_id = 0) {
  * @uses do_action() on 'trash_post_comments' before trashing
  * @uses do_action() on 'trashed_post_comments' after trashing
  *
- * @param int|object $post Post ID or object.
+ * @param int|WP_Post $post Optional. Post ID or post object.
  * @return mixed False on failure
  */
 function wp_trash_post_comments($post = null) {
@@ -2521,7 +2521,7 @@ function wp_trash_post_comments($post = null) {
  * @uses do_action() on 'untrash_post_comments' before trashing
  * @uses do_action() on 'untrashed_post_comments' after trashing
  *
- * @param int|object $post Post ID or object.
+ * @param int|WP_Post $post Optional. Post ID or post object.
  * @return mixed False on failure
  */
 function wp_untrash_post_comments($post = null) {
@@ -3039,7 +3039,7 @@ function wp_update_post( $postarr = array(), $wp_error = false ) {
  * @uses $wpdb
  * @uses do_action() Calls 'edit_post', 'save_post_{$post_type}', 'save_post' and 'wp_insert_post' on post_id and post data.
  *
- * @param int|object $post Post ID or object.
+ * @param int|WP_Post $post Post ID or post object.
  */
 function wp_publish_post( $post ) {
 	global $wpdb;
@@ -3072,7 +3072,7 @@ function wp_publish_post( $post ) {
  *
  * @since 2.5.0
  *
- * @param int $post_id Post ID.
+ * @param int|WP_Post $post_id Post ID or post object.
  * @return null Nothing is returned. Which can mean that no action is required or post was published.
  */
 function check_and_publish_future_post($post_id) {
@@ -4760,7 +4760,7 @@ function update_post_cache( &$posts ) {
  *
  * @uses do_action() Calls 'clean_post_cache' on $id before adding children (if any).
  *
- * @param int|object $post Post ID or object to remove from the cache
+ * @param int|WP_Post $post Post ID or post object to remove from the cache.
  */
 function clean_post_cache( $post ) {
 	global $_wp_suspend_cache_invalidation, $wpdb;
@@ -5039,7 +5039,7 @@ function wp_check_post_hierarchy_for_loops( $post_parent, $post_ID ) {
  *
  * @since 3.1.0
  *
- * @param int|object $post Post ID or object where thumbnail should be attached.
+ * @param int|WP_Post $post Post ID or post object where thumbnail should be attached.
  * @param int $thumbnail_id Thumbnail to attach.
  * @return bool True on success, false on failure.
  */
@@ -5060,7 +5060,7 @@ function set_post_thumbnail( $post, $thumbnail_id ) {
  *
  * @since 3.3.0
  *
- * @param int|object $post Post ID or object where thumbnail should be removed from.
+ * @param int|WP_Post $post Post ID or post object where thumbnail should be removed from.
  * @return bool True on success, false on failure.
  */
 function delete_post_thumbnail( $post ) {
diff --git a/src/wp-includes/taxonomy.php b/src/wp-includes/taxonomy.php
index a7baa167ef..410e762eae 100644
--- a/src/wp-includes/taxonomy.php
+++ b/src/wp-includes/taxonomy.php
@@ -3193,7 +3193,7 @@ function the_taxonomies($args = array()) {
  *
  * @since 2.5.0
  *
- * @param int $post Optional. Post ID or will use Global Post ID (in loop).
+ * @param int|WP_Post $post Optional. Post ID or post object.
  * @param array $args Override the defaults.
  * @return array
  */
@@ -3240,7 +3240,7 @@ function get_the_taxonomies($post = 0, $args = array() ) {
  * @since 2.5.0
  * @uses get_object_taxonomies()
  *
- * @param int $post Optional. Post ID
+ * @param int|WP_Post $post Optional. Post ID or post object.
  * @return array
  */
 function get_post_taxonomies($post = 0) {