Update phpDoc to reflect post id or object is valid

[coffee2code]

Many functions use get_post() and do so by simply passing along one of their own arguments (typically a post ID). Since get_post() accepts either a post ID or a post object, those functions therefore can (and do) also accept either type of value for the argument.

The phpDoc for many of the functions simply indicate a post ID is valid. The attached patch amends the @param doc entry for the relevant arguments to indicate either a post ID or post object is valid. (There are places where get_post() is used but the int arg is otherwise used in the function as an int -- I've skipped those since they don't really accept a post object.)

Aforementioned patch.

Good idea!

You can be a tad more specific and give the actual type of object (a stdClass) instead of just the generic object.

Replacing object with stdClass doesn't help much. If we had a WP_Post class, that would be something else.

Well, it documents that we know we're expecting an object of type stdClass, rather than some object for which we don't know the type.

I agree that a WP_Post class would be useful in terms of type-hinting, even if it only contains public properties and no methods, but that would be a different ticket.

Specifying something more specific than object warrants a separate ticket. Nowhere in WP (other than a few instances in wp-admin/includes/post.php) is stdClass used in the phpDoc to designate a param or return type. The use of "object" is the current convention.

I'm in full agreement in being more specific when we have more WP classes, such as WP_Post.

We now have WP_Post. #21309