Docs: Clarify descriptions and parameter types for various user capability checking functions.

johnbillion · johnbillion · commit 2873bcd69c12 · 2017-08-29T16:42:55.000Z
See #41017 git-svn-id: https://develop.svn.wordpress.org/trunk@41322 602fd350-edb4-49c9-b593-d223f7449a82
diff --git a/src/wp-includes/capabilities.php b/src/wp-includes/capabilities.php
@@ -565,13 +565,13 @@ function current_user_can( $capability ) {
 }
 
 /**
- * Whether current user has a capability or role for a given site.
+ * Whether the current user has a specific capability for a given site.
  *
  * @since 3.0.0
  *
  * @param int    $blog_id    Site ID.
- * @param string $capability Capability or role name.
- * @return bool
+ * @param string $capability Capability name.
+ * @return bool Whether the user has the given capability.
  */
 function current_user_can_for_blog( $blog_id, $capability ) {
 	$switched = is_multisite() ? switch_to_blog( $blog_id ) : false;
@@ -598,13 +598,13 @@ function current_user_can_for_blog( $blog_id, $capability ) {
 }
 
 /**
- * Whether author of supplied post has capability or role.
+ * Whether the author of the supplied post has a specific capability.
  *
  * @since 2.9.0
  *
- * @param int|object $post Post ID or post object.
- * @param string $capability Capability or role name.
- * @return bool
+ * @param int|WP_Post $post       Post ID or post object.
+ * @param string      $capability Capability name.
+ * @return bool Whether the post author has the given capability.
  */
 function author_can( $post, $capability ) {
 	if ( !$post = get_post($post) )
@@ -622,13 +622,13 @@ function author_can( $post, $capability ) {
 }
 
 /**
- * Whether a particular user has capability or role.
+ * Whether a particular user has a specific capability.
  *
  * @since 3.1.0
  *
- * @param int|object $user User ID or object.
- * @param string $capability Capability or role name.
- * @return bool
+ * @param int|WP_User $user       User ID or object.
+ * @param string      $capability Capability name.
+ * @return bool Whether the user has the given capability.
  */
 function user_can( $user, $capability ) {
 	if ( ! is_object( $user ) )

Original file line number	Diff line number	Diff line change
`@@ -565,13 +565,13 @@ function current_user_can( $capability ) {`
`565`	`565`	`}`
`566`	`566`
`567`	`567`	`/**`
`568`		`- * Whether current user has a capability or role for a given site.`
	`568`	`+ * Whether the current user has a specific capability for a given site.`
`569`	`569`	`*`
`570`	`570`	`* @since 3.0.0`
`571`	`571`	`*`
`572`	`572`	`* @param int $blog_id Site ID.`
`573`		`- * @param string $capability Capability or role name.`
`574`		`- * @return bool`
	`573`	`+ * @param string $capability Capability name.`
	`574`	`+ * @return bool Whether the user has the given capability.`
`575`	`575`	`*/`
`576`	`576`	`function current_user_can_for_blog( $blog_id, $capability ) {`
`577`	`577`	`$switched = is_multisite() ? switch_to_blog( $blog_id ) : false;`
`@@ -598,13 +598,13 @@ function current_user_can_for_blog( $blog_id, $capability ) {`
`598`	`598`	`}`
`599`	`599`
`600`	`600`	`/**`
`601`		`- * Whether author of supplied post has capability or role.`
	`601`	`+ * Whether the author of the supplied post has a specific capability.`
`602`	`602`	`*`
`603`	`603`	`* @since 2.9.0`
`604`	`604`	`*`
`605`		`- * @param int\|object $post Post ID or post object.`
`606`		`- * @param string $capability Capability or role name.`
`607`		`- * @return bool`
	`605`	`+ * @param int\|WP_Post $post Post ID or post object.`
	`606`	`+ * @param string $capability Capability name.`
	`607`	`+ * @return bool Whether the post author has the given capability.`
`608`	`608`	`*/`
`609`	`609`	`function author_can( $post, $capability ) {`
`610`	`610`	`if ( !$post = get_post($post) )`
`@@ -622,13 +622,13 @@ function author_can( $post, $capability ) {`
`622`	`622`	`}`
`623`	`623`
`624`	`624`	`/**`
`625`		`- * Whether a particular user has capability or role.`
	`625`	`+ * Whether a particular user has a specific capability.`
`626`	`626`	`*`
`627`	`627`	`* @since 3.1.0`
`628`	`628`	`*`
`629`		`- * @param int\|object $user User ID or object.`
`630`		`- * @param string $capability Capability or role name.`
`631`		`- * @return bool`
	`629`	`+ * @param int\|WP_User $user User ID or object.`
	`630`	`+ * @param string $capability Capability name.`
	`631`	`+ * @return bool Whether the user has the given capability.`
`632`	`632`	`*/`
`633`	`633`	`function user_can( $user, $capability ) {`
`634`	`634`	`if ( ! is_object( $user ) )`