Hook Docs: wp-admin/includes/user.php

[aaronholbrook]

Attached patch has docs for the editable_roles, get_users_drafts, and post_types_to_delete_with_user filters in wp-admin/includes/user.php.

[DrewAPicture]

Hi Aaron, thanks for the patch. Just a couple changes to make and we'll call this good:
editable_roles filter:

• If I'm not mistaken, the value of $wp_roles->roles property is an array, therefore $all_roles should be of the type array
• Space out the apply_filters line per coding standards

get_users_drafts filter:

• The value of the $query parameter and the purpose of this filter is to literally filter the query string, e.g. SELECT ID, post_title FROM wp_posts WHERE post_type = .... The filter and parameter descriptions should reflect that.
• Space out the apply_filters line per coding standards

post_types_to_delete_with_user filter

• This filter was actually introduced in 3.4.0
• The first parameter, $post_types_to_delete, is an array, not a string
• The second parameter, $id, is missing from the doc block

[DrewAPicture]

Also, I just realized you didn't document any of the action hooks in this file. Looks like you missed:

• check_passwords
• user_profile_update_errors
• delete_user
• deleted_user (duplicate, documented in wp-admin/includes/ms.php)

[DrewAPicture]

2nd pass + action docs

[DrewAPicture]

26099.2.patch​ applies the suggested changes in comment:1 and adds docs for the actions mentioned in comment:2.

[kpdesign]

@DrewAPicture: Thanks for the updated patch (26099.2.patch​​).

Just a few changes needed:

check_passwords:

• @since should be 1.5.1

editable_roles:

• Variable in @param line should be $all_roles.

delete_user:

• This is not a duplicate hook.
• @since is 2.0.0
• Space out the action line please.

deleted_user:

• Should be: /** This action is documented in wp-admin/includes/ms.php */
• Space out the action line please.

Could you make these changes and submit a new patch please? :)

[DrewAPicture]

26099.3.patch​ incorporates the suggested changes in comment:4, except for the changes on the deleted_user action.

After looking into it a little more, a switcheroo was in order. The hook was originally added to wp-admin/includes/user.php in 2.9, see [10894], and later also added to wp-admin/includes/ms.php in 3.0, see [12766].

[DrewAPicture]

In 26503:

Inline documentation for hooks in wp-admin/includes/user.php.

Props aaronholbrook for the initial patch.
Fixes #26099.