Changeset 39031

Timestamp:

10/30/2016 06:06:23 PM (10 years ago)

Author:

DrewAPicture

Message:

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

Props Soean, mrahmadawais, flixos90.
See #38398.

File:

• trunk/src/wp-includes/rest-api/endpoints/class-wp-rest-taxonomies-controller.php (modified) (10 diffs)

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

@@ -1 +1 @@
 <?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';
@@ -9 +29 @@
 
         /**
-         * 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() {
@@ -37 +62 @@
 
         /**
-         * Check whether a given request has permission to read taxonomies.
-         *
-         * @param  WP_REST_Request $request Full details about the request.
-         * @return WP_Error|boolean
+         * Checks whether a given request has permission to read taxonomies.
+         *
+         * @since 4.7.0
+         * @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 ) {
@@ -60 +88 @@
 
         /**
-         * Get all public taxonomies
-         *
-         * @param WP_REST_Request $request
-         * @return array
+         * Retrieves all public taxonomies.
+         *
+         * @since 4.7.0
+         * @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 ) {
@@ -94 +125 @@
 
         /**
-         * 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 ) {
@@ -116 +150 @@
 
         /**
-         * Get a specific taxonomy
-         *
-         * @param WP_REST_Request $request
-         * @return array|WP_Error
+         * Retrieves a specific taxonomy.
+         *
+         * @since 4.7.0
+         * @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 ) {
@@ -131 +168 @@
 
         /**
-         * Prepare a taxonomy object for serialization
-         *
-         * @param stdClass $taxonomy Taxonomy data
-         * @param WP_REST_Request $request
-         * @return WP_REST_Response $response
+         * Prepares a taxonomy object for serialization.
+         *
+         * @since 4.7.0
+         * @access public
+         *
+         * @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 ) {
@@ -168 +208 @@
 
                 /**
-                 * 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.
-                 * @param object            $item       The original taxonomy object.
-                 * @param WP_REST_Request   $request    Request used to generate the response.
+                 * @since 4.7.0
+                 *
+                 * @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 );
@@ -180 +222 @@
 
         /**
-         * Get the taxonomy's schema, conforming to JSON Schema
-         *
-         * @return array
+         * Retrieves the taxonomy's schema, conforming to JSON Schema.
+         *
+         * @since 4.7.0
+         * @access public
+         *
+         * @return array Item schema data.
          */
         public function get_item_schema() {
@@ -244 +289 @@
 
         /**
-         * Get the query params for collections
-         *
-         * @return array
+         * Retrieves the query params for collections.
+         *
+         * @since 4.7.0
+         * @access public
+         *
+         * @return array Collection parameters.
          */
         public function get_collection_params() {