Opened 13 years ago
Closed 11 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)
Change History (22)
#2
@
13 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
@
13 years ago
Replacing object with stdClass doesn't help much. If we had a WP_Post class, that would be something else.
#4
@
13 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:
↓ 11
@
13 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.
#9
@
12 years ago
- Keywords needs-patch added; has-patch removed
- Milestone changed from Future Release to 3.6
#11
in reply to:
↑ 5
;
follow-ups:
↓ 12
↓ 13
@
11 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.
#13
in reply to:
↑ 11
@
11 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.
#15
@
11 years ago
The inline @see
on new lines 447, 571, 1086, 1146, 1533 of r25567 should be wrapped in {...}
.
#16
follow-up:
↓ 17
@
11 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
@
11 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.
#20
@
11 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.
Aforementioned patch.