[wp-trac] [WordPress Trac] #25531: Hook Docs: wp-includes/capabilities.php

[WordPress Trac]

#25531: Hook Docs: wp-includes/capabilities.php
--------------------------+------------------------------
 Reporter:  ptahdunbar    |       Owner:
     Type:  defect (bug)  |      Status:  new
 Priority:  normal        |   Milestone:  Awaiting Review
Component:  Inline Docs   |     Version:
 Severity:  normal        |  Resolution:
 Keywords:  has-patch     |
--------------------------+------------------------------

Comment (by rzen):

 Ptah, solid work!

 **Overall**
 * I suggest renaming several params below, all because of how these docs
 will be read from outside the codebase. I know you named them to match
 what is literally being passed, but someone referencing these params in
 their own functions will have to rename them or else face errors of
 attempting to reference objects that don't exist. Therefore, I think it's
 most sane that we suggest logical param names up front.

 `role_has_cap`
 * Simply the `@param` variable names (e.g. $this->capabilities becomes
 $capabilities)

 `set_user_role`
 * Instead of "Perform an action after..." we could simply say "Fires
 after..."
 * Rename `$this->ID` param to `$user_id`.

 `user_has_cap`
 * You're welcome to bend the 80 character margin when its just pushing a
 single widowed word to a new line :) (http://d.pr/i/1E1b)
 * Rename `$this->allcaps` param to `$allcaps`
 * Rename `$this` param to `$user`

 `auth_post_meta_{$meta_key}`
 * You're welcome to bend the 80 character margin in the short description
 here, too. It's a bit jarring to have"post."  on a line all by its
 lonesome.
 * The first `@param` should be named something, I suggest `$allowed`.
 * The `$post->ID` param can be renamed to `$post_id`.

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