WordPress.org

Make WordPress Core

Opened 4 years ago

Closed 4 years ago

Last modified 4 years ago

#38398 closed defect (bug) (fixed)

Write proper doc blocks for the REST API endpoints

Reported by: flixos90 Owned by:
Milestone: 4.7 Priority: normal
Severity: normal Version: 4.7
Component: REST API Keywords: good-first-bug has-patch
Focuses: docs Cc:

Description

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. :)

Attachments (10)

38398.patch (9.4 KB) - added by Soean 4 years ago.
Docs: Improve documentation for WP_REST_Users_Controller.
38398.2.patch (22.8 KB) - added by Soean 4 years ago.
Docs: Improve documentation for WP_REST_Users_Controller, WP_REST_Terms_Controller, WP_REST_Taxonomies_Controller, WP_REST_Settings_Controller.
38398.3.patch (81.7 KB) - added by Soean 4 years ago.
Docs: Improve documentation for all new REST API classes.
38398.4.patch (82.3 KB) - added by Soean 4 years ago.
Small improvements in the docs
38398.5.patch (697 bytes) - added by mrahmadawais 4 years ago.
FIX: File class-wp-rest-request.php Inline comments must end with periods.
38398.6.patch (86.1 KB) - added by mrahmadawais 4 years ago.
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.
38398.7.patch (87.5 KB) - added by mrahmadawais 4 years ago.
FIX: WP Doc & Coding standards like missing end foreach() comments, periods after inline comments, file header DocBlocks, class var DocBlocks.
38398.8.patch (93.9 KB) - added by Soean 4 years ago.
Adds the @access property and some improvements.
38398.9.patch (116.1 KB) - added by flixos90 4 years ago.
38398.diff (90.0 KB) - added by DrewAPicture 4 years ago.

Download all attachments as: .zip

Change History (41)

#1 @swissspidy
4 years ago

  • Keywords good-first-bug added
  • Version set to trunk

@Soean
4 years ago

Docs: Improve documentation for WP_REST_Users_Controller.

@Soean
4 years ago

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

@Soean
4 years ago

Docs: Improve documentation for all new REST API classes.

@Soean
4 years ago

Small improvements in the docs

#2 @johnbillion
4 years ago

  • Keywords needs-docs added; needs-patch removed
  • Milestone changed from Awaiting Review to 4.7

#3 @mrahmadawais
4 years ago

@johnbillion

[UPDATE]: Nevermind, I have added the patch here, I think it would be nice to update the title of this ticket.


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!

Last edited 4 years ago by mrahmadawais (previous) (diff)

@mrahmadawais
4 years ago

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

@mrahmadawais
4 years ago

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
4 years ago

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

#4 @ocean90
4 years ago

  • Keywords has-patch added

#5 @Soean
4 years ago

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

This ticket was mentioned in Slack in #core by jeffpaul. View the logs.


4 years ago

@Soean
4 years ago

Adds the @access property and some improvements.

This ticket was mentioned in Slack in #docs by soean. View the logs.


4 years ago

This ticket was mentioned in Slack in #core-restapi by soean. View the logs.


4 years ago

@flixos90
4 years ago

#9 @flixos90
4 years ago

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.

Last edited 4 years ago by flixos90 (previous) (diff)

#10 @DrewAPicture
4 years ago

In 39011:

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

Props Soean, mrahmadawais, flixos90.
See #38398.

#11 @DrewAPicture
4 years ago

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.

#12 @DrewAPicture
4 years ago

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
4 years ago

#13 @DrewAPicture
4 years ago

  • Keywords needs-docs removed

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

Last edited 4 years ago by DrewAPicture (previous) (diff)

#14 @DrewAPicture
4 years ago

In 39021:

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

Props Soean, mrahmadawais, flixos90.
See #38398.

#15 @DrewAPicture
4 years ago

In 39022:

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

Props Soean, mrahmadawais, flixos90.
See #38398.

#16 @DrewAPicture
4 years ago

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.

#17 @DrewAPicture
4 years ago

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.

#18 @DrewAPicture
4 years ago

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.

#19 @DrewAPicture
4 years ago

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.

#20 @DrewAPicture
4 years ago

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.

#21 @DrewAPicture
4 years ago

In 39028:

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

Props Soean, mrahmadawais, flixos90.
See #38398.

#22 @DrewAPicture
4 years ago

In 39029:

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

Props mrahmadawais.
See #38398.

#23 @DrewAPicture
4 years ago

In 39030:

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

Props Soean, mrahmadawais, flixos90.
See #38398.

#24 @DrewAPicture
4 years ago

In 39031:

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

Props Soean, mrahmadawais, flixos90.
See #38398.

#25 @DrewAPicture
4 years ago

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.

#26 @DrewAPicture
4 years ago

In 39033:

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

Props Soean, mrahmadawais, flixos90.
See #38398.

#27 @DrewAPicture
4 years ago

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.

#28 @DrewAPicture
4 years ago

In 39036:

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

Props Soean, mrahmadawais, flixos90.
See #38398.

#29 @DrewAPicture
4 years ago

In 39037:

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

See #38398.

#30 @DrewAPicture
4 years ago

  • Resolution set to fixed
  • Status changed from new to closed

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.

#31 @DrewAPicture
4 years ago

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.

Note: See TracTickets for help on using tickets.