WordPress.org

Make WordPress Core

#24992 closed defect (bug) (fixed)

phpDoc patch for wp-admin/includes/user.php

Reported by: tivnet Owned by: SergeyBiryukov
Milestone: 3.7 Priority: normal
Severity: trivial Version: 3.6
Component: Inline Docs Keywords: has-patch commit
Focuses: Cc:

Description

@return should start with WP_User

Attachments (3)

user.php.patch (396 bytes) - added by tivnet 23 months ago.
24992.patch (582 bytes) - added by SergeyBiryukov 22 months ago.
24992.2.patch (1.9 KB) - added by SergeyBiryukov 22 months ago.

Download all attachments as: .zip

Change History (13)

@tivnet23 months ago

comment:1 follow-up: @DrewAPicture23 months ago

  • Milestone Awaiting Review deleted
  • Resolution set to invalid
  • Status changed from new to closed

It's core style to delineate the return type as object, and use the description to specify the kind of object.

comment:2 in reply to: ↑ 1 ; follow-up: @tivnet23 months ago

  • Resolution invalid deleted
  • Status changed from closed to reopened

Replying to DrewAPicture:

It's core style to delineate the return type as object, and use the description to specify the kind of object.

First of all, if that's a "core style" then it's time to change this style, because modern IDE's use phpDoc to validate code and provide prompts. "Object" won't help.

Besides, take a look at get_post() - what does it say there? Yes, WP_Post.
wp_insert_post does not say object in @return.
get_page returns WP_Post
Same for get_default_post_to_edit
get_current_screen returns WP_Screen

If you are not convinced, can I ask for a second opinion?
Thank you!

comment:3 @markoheijnen23 months ago

  • Milestone set to 3.7

The patch seems totally fine with me.

comment:4 in reply to: ↑ 2 @DrewAPicture23 months ago

  • Version set to 3.6

Replying to tivnet:

Replying to DrewAPicture:

It's core style to delineate the return type as object, and use the description to specify the kind of object.

First of all, if that's a "core style" then it's time to change this style, because modern IDE's use phpDoc to validate code and provide prompts. "Object" won't help.

I was mistaken, in terms of using named class objects in the phpdoc return tags. This section of the phpdoc standard for WordPress hasn't been written yet ;) I'll add it to my list.

+1 for user.php.patch

@SergeyBiryukov22 months ago

comment:5 follow-up: @SergeyBiryukov22 months ago

get_userdata() can also return false, we should probably take that into account: 24992.patch.

comment:6 in reply to: ↑ 5 @tivnet22 months ago

Replying to SergeyBiryukov:
Maybe WP_User|bool ? Generally, it returns WP_User. Bool is an exception.

@SergeyBiryukov22 months ago

comment:7 @SergeyBiryukov22 months ago

24992.2.patch brings some consistency.

comment:8 @SergeyBiryukov22 months ago

  • Keywords commit added

comment:10 @SergeyBiryukov22 months ago

  • Owner set to SergeyBiryukov
  • Resolution set to fixed
  • Status changed from reopened to closed

In 25204:

Update phpdoc for get_user_to_edit(), get_userdata(), and get_user_by(). props tivnet. fixes #24992.

Note: See TracTickets for help on using tickets.