[wp-trac] [WordPress Trac] #25533: Hooks Docs: wp-includes/user.php

[WordPress Trac]

#25533: Hooks Docs: wp-includes/user.php
---------------------------+------------------------------
 Reporter:  stephenharris  |       Owner:  DrewAPicture
     Type:  defect (bug)   |      Status:  reviewing
 Priority:  normal         |   Milestone:  Awaiting Review
Component:  Inline Docs    |     Version:
 Severity:  normal         |  Resolution:
 Keywords:  needs-patch    |
---------------------------+------------------------------
Changes (by DrewAPicture):

 * keywords:  has-patch => needs-patch


Comment:

 Hi, thanks for the patch. Some notes on [attachment:25533.diff]:
 Overall:
 * Space out the specific filter or hook links per coding standards
 * s/Triggered/Fires
 * s/Filters/Filter

 `wp_authenticate` hook:
 * Change "Triggered before the user is logged in." to "Fires before the
 user is authenticated."
 * Need a blank line after the long description
 * Parameters need descriptions with periods

 `secure_signon_cookie` filter:
 * Comma after "User credentials" should be a period.
 * Add the boolean default to the `$remember` doc line. Wrap the line to
 align with the beginning of the parameter description.

 `wp_login` hook:
 * Assign `$user->user_login` to `$user_login` just above the doc block.
 Whenever possible, try to avoid documenting variables that don't exist.
 * Parameter descriptions need periods.
 * "usersname" is misspelled

 `wp_authenticate_user` filter:
 * The first part of the description is redundant as that information
 belongs in the first parameter description. Maybe just use "Filter whether
 the given user can be authenticated with the provided $password."
 * Wrap the long description at "filtered" and try to keep lines at ~80
 character width, expanding up to ~120 if necessary
 * The `$user` parameter variable is missing from the `@param` line. The
 description here can also be shortened a bit, something like "WP_User
 object or WP_Error object if a previous callback failed authentication."

 `check_is_user_spammed` filter:
 * Assign `is_user_spammy()` to `$spammed`

 `get_user_option_{$option}` filter:
 * Describe what the `$option` portion of the dynamic hook name refers to
 in a long description.
 * Add the `$result` variable to the first parameter line.

 `user_search_columns` filter:
 * Specify the default search columns in either the parameter description
 or a long description for the filter. They appear to be 'ID',
 'user_login', 'user_email', 'user_url', 'user_nicename'.
 * `$this` refers to the current `WP_User_Query` instance

 `pre_user_query` hook:
 * Remove the first sentence in the long description, and instead add ",
 passed by reference" to the end of the parameter description.
 * Change "It contains" to "The query contains"

 `found_users_query` filter:
 * Assign `'SELECT FOUND_ROWS()'` to `$sql`, add a parameter description
 with a period.

 `get_blogs_of_user` filter:
 * Add `$blogs` variable to the parameter doc.
 * Wrap the third parameter description to align with the beginning of the
 description.

 `wp_dropdown_users` filter:
 * Add `$output` variable to the parameter doc.

 `edit_{$field}` filter:
 * Just mark it `//duplicate_hook` (it's already documented in another
 file)

 `edit_user_{$field}` filter:
 * Add a proper short description
 * Lines need to be spaced out per the inline docs template
 * Use a long description to describe what the `$field` portion of the
 dynamic hook name refers to.
 * Needs parameter docs for `$value` and `$userid`
 * Remove the `@see` line

 `pre_{$field}` filter:
 * `//duplicate_hook`

 `pre_user_{$field}` filter:
 * Add a proper short description
 * Lines need to be spaced out per the inline docs template
 * Use a long description to describe what the `$field` portion of the
 dynamic hook name refers to.
 * Needs parameter docs for `$value`
 * Remove the `@see` line

 `$field` filter:
 * `//duplicate_hook`

 `user_{$field}` filter:
 * Add a proper short description
 * Lines need to be spaced out per the inline docs template
 * Use a long description to describe what the `$field` portion of the
 dynamic hook name refers to.
 * Needs parameter docs for `$value`, `$user_id`, and `$context`
 * Remove the `@see` line

 `validate_username` filter:
 * Add `$valid` to the first parameter doc
 * Add `$username` to the second parameter doc

 `pre_user_nicename`, `pre_user_url`, `pre_user_email`,
 `pre_user_first_name`, `pre_user_last_name`, `pre_user_display_name`,
 `pre_user_description` filters:
 * Parameters need a description with a period.

 `profile_update`, `user_registered`, `password_reset` hooks:
 * Parameter descriptions need periods.

 `registration_errors` filter:
 * Wrap the long description at "invalid"` and align new lines with the
 beginning of the description using spaces

--
Ticket URL: <http://core.trac.wordpress.org/ticket/25533#comment:2>
WordPress Trac <http://core.trac.wordpress.org/>
WordPress blogging software