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

[coffee2code]

Aforementioned patch.

[scribu]

Good idea!

[GaryJ]

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

[scribu]

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

[GaryJ]

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.

[coffee2code]

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.

[ryan]

We now have WP_Post. #21309

[ericlewis]

Replying to coffee2code:

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

Now that we have the WP_Post class, how do you imagine documenting all the accepted types here?

Something like this?

@param int|WP_Post|stdClass $post Post ID, WP_Post object, or stdClass resembling a post. Optional, default is the current post from the loop.

[DrewAPicture]

Replying to ericlewis:

Replying to coffee2code:

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

Now that we have the WP_Post class, how do you imagine documenting all the accepted types here?

Something like this?

@param int|WP_Post|stdClass $post Post ID, WP_Post object, or stdClass resembling a post. Optional, default is the current post from the loop.

The type should be object, leaving the parameter description to spell out which object types are accepted.

[DrewAPicture]

Replying to ericlewis:

Replying to coffee2code:

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

Now that we have the WP_Post class, how do you imagine documenting all the accepted types here?

Something like this?

@param int|WP_Post|stdClass $post Post ID, WP_Post object, or stdClass resembling a post. Optional, default is the current post from the loop.

That seems ok.

[DrewAPicture]

In 25567:

Inline documentation improvements for wp-includes/comment-template.php.

Changes include:

• Existing phpdoc block improvements
• Inclusion of defaults for optional parameters
• Hash-notated argument arrays
• Removal of unnecessary or redundant tagging.

Also standardization of int|WP_Post function parameters.

These changes clear the way toward less redundancy for hook docs in a future ticket.

Still left: Fully documented arguments in comment_form() and a pass through Walker_Comment.

See #20495. See #25388.

[GaryJ]

The inline @see on new lines 447, 571, 1086, 1146, 1533 of r25567 should be wrapped in {...}.

[GaryJ]

According to the ​draft PSR, all of the Inline PHPDoc bits (the array keys) should still be proceeded with a $ for readability and parsability. The latest commit here uses 'foobar' instead of $foobar.

[DrewAPicture]

Replying to GaryJ:

According to the ​draft PSR, all of the Inline PHPDoc bits (the array keys) should still be proceeded with a $ for readability and parsability. The latest commit here uses 'foobar' instead of $foobar.

This is intentional. Please see the ​documenting functional argument arrays section of the WordPress inline documentation standards.

WordPress uses a customized documentation schema that draws inspiration from PHPDoc, but that does not directly adhere to the PSR-*/FIG spec. We use our ​own parser and our ​own standards.

If you have a suggestion or constructive criticism, I invite you to join us for the weekly inline-docs chat, held Wednesdays at 18:00 UTC in #wordpress-sfd on Freenode.

[DrewAPicture]

In 27156:

Inline documentation cleanup in wp-includes/comment-template.php.

This cleanup follows [25567] and brings the docs in-line with standards that at the time had not yet been finalized.

These changes include

• Moving in-line @see tags to their own lines
• Using docs-specific variables in hook docs
• Fixing line-wrapping throughout
• Typos and punctuation
• Converting hash notation values to variables per the standard

Fixes #27083. See #20495.

[DrewAPicture]

[27473] covers @coffee2code's original patch, standardizing on int|WP_Post where applicable per a conversation I with nacin several months ago.

Closing this ticket in favor of handling any similar cases in separate functional doc tickets.