[wp-trac] [WordPress Trac] #38398: Write proper doc blocks for the REST API endpoints

[WordPress Trac]

#38398: Write proper doc blocks for the REST API endpoints
-------------------------------------------------+--------------------
 Reporter:  flixos90                             |       Owner:
     Type:  defect (bug)                         |      Status:  new
 Priority:  normal                               |   Milestone:  4.7
Component:  REST API                             |     Version:  trunk
 Severity:  normal                               |  Resolution:
 Keywords:  good-first-bug needs-docs has-patch  |     Focuses:  docs
-------------------------------------------------+--------------------

Comment (by flixos90):

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

 I did an initial review 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`.

--
Ticket URL: <https://core.trac.wordpress.org/ticket/38398#comment:9>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform