WordPress.org

Make WordPress Core

Opened 8 years ago

Closed 6 years ago

#20495 closed defect (bug) (fixed)

Update phpDoc to reflect post id or object is valid

Reported by: coffee2code Owned by:
Milestone: 3.9 Priority: normal
Severity: trivial Version: 3.3.1
Component: Posts, Post Types Keywords:
Focuses: docs Cc:

Description

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

Attachments (2)

20495.diff (10.7 KB) - added by coffee2code 8 years ago.
Aforementioned patch.
20495.2.diff (8.5 KB) - added by DrewAPicture 6 years ago.

Download all attachments as: .zip

Change History (22)

@coffee2code
8 years ago

Aforementioned patch.

#1 @scribu
8 years ago

Good idea!

#2 @GaryJ
8 years ago

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

#3 @scribu
8 years ago

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

#4 @GaryJ
8 years ago

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.

#5 follow-up: @coffee2code
8 years ago

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.

#6 @ocean90
8 years ago

  • Milestone changed from Awaiting Review to 3.5

#7 @ryan
8 years ago

We now have WP_Post. #21309

#8 @ryan
8 years ago

  • Milestone changed from 3.5 to Future Release

#9 @helen
8 years ago

  • Keywords needs-patch added; has-patch removed
  • Milestone changed from Future Release to 3.6

#10 @ryan
7 years ago

  • Milestone changed from 3.6 to Future Release

#11 in reply to: ↑ 5 ; follow-ups: @ericlewis
7 years ago

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.

#12 in reply to: ↑ 11 @DrewAPicture
7 years ago

Edit: nevermind.

Last edited 7 years ago by DrewAPicture (previous) (diff)

#13 in reply to: ↑ 11 @DrewAPicture
7 years ago

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.

#14 @DrewAPicture
7 years ago

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.

Last edited 7 years ago by DrewAPicture (previous) (diff)

#15 @GaryJ
7 years ago

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

#16 follow-up: @GaryJ
7 years ago

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.

#17 in reply to: ↑ 16 @DrewAPicture
7 years ago

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.

#18 @nacin
7 years ago

  • Component changed from Inline Docs to Post Types
  • Focuses docs added

#19 @DrewAPicture
6 years ago

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
6 years ago

#20 @DrewAPicture
6 years ago

  • Keywords needs-patch removed
  • Milestone changed from Future Release to 3.9
  • Resolution set to fixed
  • Status changed from new to closed

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

Note: See TracTickets for help on using tickets.