Clarify shortcomings of register_meta about docs-v2

[kadamwhite]

I've added this section to the Modifying Responses guide in the handbook: I'm going to mark this as resolved with this addition, we can re-open if further clarification is needed.

Using register_rest_field vs register_meta

There are two methods which can be used to add data to WordPress REST API responses, register_rest_field and register_meta.

register_rest_field may be used to add arbitrary fields to any REST API response, and can be used to both read and write data using the API. To register a new REST field you must provide your own callback functions to get or set the field's value, as well as manually specify your own schema definition for the field.

register_meta is used to whitelist an existing custom meta value for access through the REST API. By setting a meta field's show_in_rest parameter to true, that field's value will be exposed on a .meta key in the endpoint response, and WordPress will handle setting up the callbacks for reading and writing to that meta key. This is much simpler than register_rest_field, with one caveat:

[alert]
Meta fields set to show_in_rest using register_meta are registered for all objects of a given type. If one custom post type shows a meta field, all custom post types will show that meta field.
[/alert]

This is because meta registration is currently handled at the base level of WordPress object (post, user, etc) and cannot be specified per "subtype" (e.g. custom post types). This limitation may be improved in future versions of WordPress, but if you are trying to add a custom field to a specific API endpoint's response then register_rest_field is currently recommended over register_meta.

[garubi]

Also I think that should be explained if is wrong or right to use register_meta() instead of register_rest_field() when the meta field is intended to be used only with one or some custom posts (or taxonomies).