Post meta authorization filter docs are incorrect

[ericlewis]

The ​doc for the auth_post_meta_* filter says

Filter whether the user is allowed to add post meta to a post.

This is not actually the case. If the filter returns false, the user will need to have the edit_post_meta cap. Otherwise, edit_post mapped meta caps apply.

[lukecavanagh]

Let me work on a patch.

[johneckman]

Patch to docs section to clarify filters.

[johneckman]

36319.patch includes comments to try to clarify how these filters interact.

For clarity, added brackets to nested if( ! $allowed) statement as it is unclear as an inline if.

[adamsilverstein]

@johneckman thanks for your patch here!

I had a little trouble getting the patch to apply because things have moved around quite a bit. The original inline documentation for both hooks was removed and replaced with This filter is documented in wp-includes/meta.php - when I looked there I did not find similar hooks or inline documentation.

36319.2.patch​ is an update against trunk and also helps clarify the functionality I think. Can you please review and let me know what you think?

[DrewAPicture]

@adamsilverstein So, we should at the very least document the auth_{$object_type}_meta_{$meta_key} hook as having been introduced in 3.3.0. The way we handle hooks getting renamed is like this:

 * @since 3.3.0 As 'auth_post_meta_{$meta_key}'.
 * @since 4.8.0

I'm unsure about whether the other original hook was maintained in the rename. If it was, the same procedure applies. If not, we need to properly deprecate the old hook.

[adamsilverstein]

@DrewAPicture thanks for the feedback and syntax clarification. I tracked down the origin of each filter and made sure to have an @since line listing the previous use in both cases. Does 36319.diff​ look good?

[DrewAPicture]

@adamsilverstein Looks good. We should probably do inline @see notations for the dynamic hook references in the descriptions, but you can fix that on commit.

Just make sure to remove the extra curly braces so the parser doesn't get confused, e.g. Use the {@see 'auth_$object_type_$sub_type_meta_$meta_key'} filter ...

You want to do the honors? :-)

[DrewAPicture]

@coffee2code: Leaving a note here that we should manually pick up these docs in the 4.8.1 re-parse.

[adamsilverstein]

@DrewAPicture Thanks for the feedback, does 36319.2.diff​ look right? Happy to commit once I get your confirmation!

[DrewAPicture]

@adamsilverstein Looks good except for what looks like copy pasta in the first one: "{@see{@see auth_post_$object_type_meta_$meta_key}".

[adamsilverstein]

36319.3.diff​ fix a copy/paste typo

[adamsilverstein]

In 41800:

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.