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

Props Soean, mrahmadawais, flixos90.
See #38398.


git-svn-id: https://develop.svn.wordpress.org/trunk@39031 602fd350-edb4-49c9-b593-d223f7449a82

src/wp-includes/rest-api/endpoints/class-wp-rest-taxonomies-controller.php

@@ -1,14 +1,39 @@
 <?php
+/**
+ * REST API: WP_REST_Taxonomies_Controller class
+ *
+ * @package WordPress
+ * @subpackage REST_API
+ * @since 4.7.0
+ */
 
+/**
+ * Core class used to manage taxonomies via the REST API.
+ *
+ * @since 4.7.0
+ *
+ * @see WP_REST_Controller
+ */
 class WP_REST_Taxonomies_Controller extends WP_REST_Controller {
 
+	/**
+	 * Constructor.
+	 *
+	 * @since 4.7.0
+	 * @access public
+	 */
 	public function __construct() {
 		$this->namespace = 'wp/v2';
 		$this->rest_base = 'taxonomies';
 	}
 
 	/**
-	 * Register the routes for the objects of the controller.
+	 * Registers the routes for the objects of the controller.
+	 *
+	 * @since 4.7.0
+	 * @access public
+	 *
+	 * @see register_rest_route()
 	 */
 	public function register_routes() {
 
@@ -36,10 +61,13 @@ class WP_REST_Taxonomies_Controller extends WP_REST_Controller {
 	}
 
 	/**
-	 * Check whether a given request has permission to read taxonomies.
+	 * Checks whether a given request has permission to read taxonomies.
 	 *
-	 * @param  WP_REST_Request $request Full details about the request.
+	 * @since 4.7.0
-	 * @return WP_Error|boolean
+	 * @access public
+	 *
+	 * @param WP_REST_Request $request Full details about the request.
+	 * @return true|WP_Error True if the request has read access, WP_Error object otherwise.
 	 */
 	public function get_items_permissions_check( $request ) {
 		if ( 'edit' === $request['context'] ) {
@@ -59,10 +87,13 @@ class WP_REST_Taxonomies_Controller extends WP_REST_Controller {
 	}
 
 	/**
-	 * Get all public taxonomies
+	 * Retrieves all public taxonomies.
 	 *
-	 * @param WP_REST_Request $request
+	 * @since 4.7.0
-	 * @return array
+	 * @access public
+	 *
+	 * @param WP_REST_Request $request Full details about the request.
+	 * @return WP_REST_Response Response object on success, or WP_Error object on failure.
 	 */
 	public function get_items( $request ) {
 
@@ -93,10 +124,13 @@ class WP_REST_Taxonomies_Controller extends WP_REST_Controller {
 	}
 
 	/**
-	 * Check if a given request has access a taxonomy
+	 * Checks if a given request has access to a taxonomy.
+	 *
+	 * @since 4.7.0
+	 * @access public
 	 *
 	 * @param  WP_REST_Request $request Full details about the request.
-	 * @return WP_Error|boolean
+	 * @return true|WP_Error True if the request has read access for the item, otherwise false or WP_Error object.
 	 */
 	public function get_item_permissions_check( $request ) {
 
@@ -115,10 +149,13 @@ class WP_REST_Taxonomies_Controller extends WP_REST_Controller {
 	}
 
 	/**
-	 * Get a specific taxonomy
+	 * Retrieves a specific taxonomy.
 	 *
-	 * @param WP_REST_Request $request
+	 * @since 4.7.0
-	 * @return array|WP_Error
+	 * @access public
+	 *
+	 * @param WP_REST_Request $request Full details about the request.
+	 * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
 	 */
 	public function get_item( $request ) {
 		$tax_obj = get_taxonomy( $request['taxonomy'] );
@@ -130,11 +167,14 @@ class WP_REST_Taxonomies_Controller extends WP_REST_Controller {
 	}
 
 	/**
-	 * Prepare a taxonomy object for serialization
+	 * Prepares a taxonomy object for serialization.
 	 *
-	 * @param stdClass $taxonomy Taxonomy data
+	 * @since 4.7.0
-	 * @param WP_REST_Request $request
+	 * @access public
-	 * @return WP_REST_Response $response
+	 *
+	 * @param stdClass        $taxonomy Taxonomy data.
+	 * @param WP_REST_Request $request  Full details about the request.
+	 * @return WP_REST_Response Response object.
 	 */
 	public function prepare_item_for_response( $taxonomy, $request ) {
 
@@ -167,21 +207,26 @@ class WP_REST_Taxonomies_Controller extends WP_REST_Controller {
 		) );
 
 		/**
-		 * Filter a taxonomy returned from the API.
+		 * Filters a taxonomy returned from the REST API.
 		 *
 		 * Allows modification of the taxonomy data right before it is returned.
 		 *
-		 * @param WP_REST_Response  $response   The response object.
+		 * @since 4.7.0
-		 * @param object            $item       The original taxonomy object.
+		 *
-		 * @param WP_REST_Request   $request    Request used to generate the response.
+		 * @param WP_REST_Response $response The response object.
+		 * @param object           $item     The original taxonomy object.
+		 * @param WP_REST_Request  $request  Request used to generate the response.
 		 */
 		return apply_filters( 'rest_prepare_taxonomy', $response, $taxonomy, $request );
 	}
 
 	/**
-	 * Get the taxonomy's schema, conforming to JSON Schema
+	 * Retrieves the taxonomy's schema, conforming to JSON Schema.
 	 *
-	 * @return array
+	 * @since 4.7.0
+	 * @access public
+	 *
+	 * @return array Item schema data.
 	 */
 	public function get_item_schema() {
 		$schema = array(
@@ -243,9 +288,12 @@ class WP_REST_Taxonomies_Controller extends WP_REST_Controller {
 	}
 
 	/**
-	 * Get the query params for collections
+	 * Retrieves the query params for collections.
 	 *
-	 * @return array
+	 * @since 4.7.0
+	 * @access public
+	 *
+	 * @return array Collection parameters.
 	 */
 	public function get_collection_params() {
 		$new_params = array();