Write proper doc blocks for the REST API endpoints

[flixos90]

Many aspects of the new API endpoints and meta fields classes do not have proper documentation following the WordPress standards yet. We should make sure they do (file headers, third-person singular verbs, access/since annotations, parameter and return value descriptions etc).

I will gladly take care of some of it, but wouldn't mind help. Maybe we can get a small group together and assign a set of related classes (or maybe even similar methods in different classes) to everyone, in order to make this an easy task. :)

[Soean]

Docs: Improve documentation for WP_REST_Users_Controller.

[Soean]

Docs: Improve documentation for WP_REST_Users_Controller, WP_REST_Terms_Controller, WP_REST_Taxonomies_Controller, WP_REST_Settings_Controller.

[Soean]

Docs: Improve documentation for all new REST API classes.

[Soean]

Small improvements in the docs

[mrahmadawais]

@johnbillion There are several WordPress Coding Standards issue in the REST API files. I'd like to address them, would this be the right ticket for it? If so, it needs to be edited as such. Otherwise, I can create a new ticket about "REST API Files To Follow WP Coding Standards".

To help you better understand it better, in class-wp-rest-request.php there is a Yoda conditions issue... Addressing it and posting it here under "Write proper doc blocks for the REST API endpoints" feels a bit weird per se.

Looking forward!

[mrahmadawais]

FIX: File class-wp-rest-request.php Inline comments must end with periods.

[mrahmadawais]

FIX: WP Doc & Coding standards in class-wp-rest-request.php, class-wp-rest-response.php, and class-wp-rest-server.php. Addresses missing foreach() endings, space after foreach, yoda conditions, replaced esle if with elseif.

[mrahmadawais]

FIX: WP Doc & Coding standards like missing end foreach() comments, periods after inline comments, file header DocBlocks, class var DocBlocks.

[Soean]

The @access property has to be added to the methods.

[Soean]

Adds the @access property and some improvements.

[flixos90]

Thanks for all the great work and patches @Soean and @mrahmadawais!

I did an initial review (38398.9.patch​) and made the following adjustments:

• the third-person singular form is now applied to all method descriptions
• the term boolean (for method and hook parameters) is now replaced with bool
• the class headers are more meaningful and similar to other Core classes

Other small issues I encountered which further review should happen on (I adjusted several instances, but probably not everything yet):

• there are still several parameter descriptions missing
• sometimes parameters are indented wrong
• words like "comment", "attachment" and such should probably not be capitalized

Another notice (not docs-related): Some implementations of abstract methods return WP_Rest_Response objects while others return arrays. This will not cause bugs at this point (since they are parsed afterwards anyway), but we might wanna align them to all return proper response objects. A similar issue with permission checks, most of them return WP_Error objects on failure, but some of them return either WP_Error or boolean false - maybe we can also provide proper error objects for those that only return false.

[DrewAPicture]

In 39011:

Docs: Add much more complete and syntactically correct documentation throughout the WP_REST_Attachments_Controller class.

Props Soean, mrahmadawais, flixos90.
See #38398.

[DrewAPicture]

In 39014:

Docs: Add much more complete and syntactically correct documentation throughout the WP_REST_Comment_Meta_Fields class.

Props Soean, mrahmadawais, flixos90.
See #38398.

[DrewAPicture]

In 39015:

Docs: Add much more complete and syntactically correct documentation throughout the WP_REST_Comments_Controller class.

Props Soean, mrahmadawais, flixos90.
See #38398.

[DrewAPicture]

38398.diff​ is an updated version of 38398.9.patch​ following the last three commits.

[DrewAPicture]

In 39021:

Docs: Add much more complete and syntactically correct documentation throughout the WP_REST_Controller class.

Props Soean, mrahmadawais, flixos90.
See #38398.

[DrewAPicture]

In 39022:

Docs: Add much more complete and syntactically correct documentation throughout the WP_REST_Meta_Fields class.

Props Soean, mrahmadawais, flixos90.
See #38398.

[DrewAPicture]

In 39023:

Docs: Add much more complete and syntactically correct documentation throughout the WP_REST_Post_Meta_Fields class.

Props Soean, mrahmadawais, flixos90.
See #38398.

[DrewAPicture]

In 39024:

Docs: Add much more complete and syntactically correct documentation throughout the WP_REST_Post_Statuses_Controller class.

Props Soean, mrahmadawais, flixos90.
See #38398.

[DrewAPicture]

In 39025:

Docs: Add much more complete and syntactically correct documentation throughout the WP_REST_Post_Types_Controller class.

Props Soean, mrahmadawais, flixos90.
See #38398.

[DrewAPicture]

In 39026:

Docs: Add much more complete and syntactically correct documentation throughout the WP_REST_Posts_Controller class.

Props Soean, mrahmadawais, flixos90, DrewAPicture.
See #38398.

[DrewAPicture]

In 39027:

REST: Fix a yoda condition in WP_REST_Request::get_parameter_order() and add a missing period for an inline comment in `WP_REST_Request::from_url().

Props mrahmadawais.
See #38398.

[DrewAPicture]

In 39028:

Docs: Add much more complete and syntactically correct documentation throughout the WP_REST_Revisions_Controller class.

Props Soean, mrahmadawais, flixos90.
See #38398.

[DrewAPicture]

In 39029:

REST: Fix some errant else if conditions and add a few missing periods on inline comments.

Props mrahmadawais.
See #38398.

[DrewAPicture]

In 39030:

Docs: Add much more complete and syntactically correct documentation throughout the WP_REST_Settings_Controller class.

Props Soean, mrahmadawais, flixos90.
See #38398.

[DrewAPicture]

In 39031:

Docs: Add much more complete and syntactically correct documentation throughout the WP_REST_Taxonomies_Controller class.

Props Soean, mrahmadawais, flixos90.
See #38398.

[DrewAPicture]

In 39032:

Docs: Add much more complete and syntactically correct documentation throughout the WP_REST_Term_Meta_Fields class.

Props Soean, mrahmadawais, flixos90.
See #38398.

[DrewAPicture]

In 39033:

Docs: Add much more complete and syntactically correct documentation throughout the WP_REST_Terms_Controller class.

Props Soean, mrahmadawais, flixos90.
See #38398.

[DrewAPicture]

In 39034:

Docs: Add much more complete and syntactically correct documentation throughout the WP_REST_User_Meta_Fields class.

Props Soean, mrahmadawais, flixos90.
See #38398.

[DrewAPicture]

In 39036:

Docs: Add much more complete and syntactically correct documentation throughout the WP_REST_Users_Controller class.

Props Soean, mrahmadawais, flixos90.
See #38398.

[DrewAPicture]

In 39037:

Docs: Add a slightly less ambiguous list of return types for rest_ensure_response().

See #38398.

[DrewAPicture]

I think that covers all of the docs fixes in the latest patch 38398.diff​ and 38398.9.patch​.

Closing this out in favor of new tickets for docs fixes in specific files.

[DrewAPicture]

In 39049:

Docs: The query_vars filter used in the REST posts controller should be notated as a duplicate rather than a new hook.

See #38398.