current_user_can function is able to take post_id as argument, but it is not documented in WordPress documentation.

[jliman]

The function current_user_can is documented with one parameter, but if we look at the code, it actually support post_id as the argument.

[dd32]

In other areas we've documented it as such (WP_User::has_cap() is what current_user_can() wraps)

The second optional parameter can also be used to check for capabilities against a specific object, such as a post or user.

​https://developer.wordpress.org/reference/classes/wp_user/has_cap/

[DrewAPicture]

Yeah, we're pretty bad about documenting functions that leverage func_get_args() for variable numbers of arguments.

I distinctly remember being frustrated by the lack of documentation on add_query_arg(), for instance, so I added some parameter docs there. We should probably do an audit and actually try to document any of these "variable-argument" functions in core.

[DrewAPicture]

I would like to get this done in 4.4, along with better docs for add_query_arg() and others.

@jliman, are you interested in trying your hand at ​submitting a patch?

[jliman]

Added optional parameter information.

[DrewAPicture]

+ map_meta_cap

[DrewAPicture]

In 34224:

Docs: Add documentation for $object_id, the optional second parameter in current_user_can() and WP_User::has_cap(), and the optional third parameter in map_meta_cap().

This change introduces the vernacular of "meta" vs "primitive" capabilities to core docs, and providing examples for each inline and attempts to make it clear that $object_id is really only useful if the passed $capability is of the meta cap variety.

Props jliman for the initial patch.
Fixes #32694.