From ca3082254174ffff809e570b06b8334b55343601 Mon Sep 17 00:00:00 2001
From: Adam Silverstein <adamsilverstein@earthboundhosting.com>
Date: Mon, 9 Oct 2017 19:14:52 +0000
Subject: [PATCH] Docs: add docs for meta authorization filters.

Add filter documentation for `auth_{$object_type}_meta_{$meta_key}` and `auth_{$object_type}_{$sub_type}_meta_{$meta_key}`.

Props ericlewis, johneckman, DrewAPicture.
Fixes #36319.

Built from https://develop.svn.wordpress.org/trunk@41800


git-svn-id: http://core.svn.wordpress.org/trunk@41634 1a063a9b-81f0-0310-95a4-ce76da25c4cd
---
 wp-includes/capabilities.php | 42 ++++++++++++++++++++++++++++++++++--
 wp-includes/version.php      |  2 +-
 2 files changed, 41 insertions(+), 3 deletions(-)

diff --git a/wp-includes/capabilities.php b/wp-includes/capabilities.php
index 90eb4cbfe1..2279c16b62 100644
--- a/wp-includes/capabilities.php
+++ b/wp-includes/capabilities.php
@@ -308,10 +308,48 @@ function map_meta_cap( $cap, $user_id ) {
 
 		$has_filter = has_filter( "auth_{$object_type}_meta_{$meta_key}" ) || has_filter( "auth_{$object_type}_{$sub_type}_meta_{$meta_key}" );
 		if ( $meta_key && $has_filter ) {
-			/** This filter is documented in wp-includes/meta.php */
+
+			/**
+			 * Filters whether the user is allowed to edit meta.
+			 *
+			 * Use the {@see auth_post_$object_type_meta_$meta_key} filter to modify capabilities for
+			 * specific object types. Return true to have the mapped meta caps from edit_{$object_type} apply.
+			 *
+			 * The dynamic portion of the hook name, `$object_type` refers to the object type being filtered.
+			 * The dynamic portion of the hook name, `$meta_key`, refers to the meta key passed to map_meta_cap().
+			 *
+			 * @since 3.3.0 As 'auth_post_meta_{$meta_key}'.
+			 * @since 4.6.0
+			 *
+			 * @param bool   $allowed  Whether the user can add the post meta. Default false.
+			 * @param string $meta_key The meta key.
+			 * @param int    $post_id  Post ID.
+			 * @param int    $user_id  User ID.
+			 * @param string $cap      Capability name.
+			 * @param array  $caps     User capabilities.
+			 */
 			$allowed = apply_filters( "auth_{$object_type}_meta_{$meta_key}", false, $meta_key, $object_id, $user_id, $cap, $caps );
 
-			/** This filter is documented in wp-includes/meta.php */
+			/**
+			 * Filters whether the user is allowed to add post meta to a post of a given type.
+			 *
+			 * Use the {@see auth_$object_type_$sub_type_meta_$meta_key} filter to modify capabilities for
+			 * specific object types/subtypes. Return true to have the mapped meta caps from edit_{$object_type} apply.
+			 *
+			 * The dynamic portion of the hook name, `$object_type` refers to the object type being filtered.
+			 * The dynamic portion of the hook name, `$sub_type` refers to the object subtype being filtered.
+			 * The dynamic portion of the hook name, `$meta_key`, refers to the meta key passed to map_meta_cap().
+			 *
+			 * @since 4.6.0 As 'auth_post_{$post_type}_meta_{$meta_key}'.
+			 * @since 4.7.0
+			 *
+			 * @param bool   $allowed  Whether the user can add the post meta. Default false.
+			 * @param string $meta_key The meta key.
+			 * @param int    $post_id  Post ID.
+			 * @param int    $user_id  User ID.
+			 * @param string $cap      Capability name.
+			 * @param array  $caps     User capabilities.
+			 */
 			$allowed = apply_filters( "auth_{$object_type}_{$sub_type}_meta_{$meta_key}", $allowed, $meta_key, $object_id, $user_id, $cap, $caps );
 
 			if ( ! $allowed ) {
diff --git a/wp-includes/version.php b/wp-includes/version.php
index 9ce48785cd..8125731780 100644
--- a/wp-includes/version.php
+++ b/wp-includes/version.php
@@ -4,7 +4,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '4.9-beta1-41799';
+$wp_version = '4.9-beta1-41800';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.