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

Props Soean, mrahmadawais, flixos90.
See #38398.


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

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

@@ -1,18 +1,36 @@
 <?php
+/**
+ * REST API: WP_REST_Comments_Controller class
+ *
+ * @package WordPress
+ * @subpackage REST_API
+ * @since 4.7.0
+ */
 
 /**
- * Access comments
+ * Core controller used to access comments via the REST API.
+ *
+ * @since 4.7.0
+ *
+ * @see WP_REST_Controller
  */
 class WP_REST_Comments_Controller extends WP_REST_Controller {
 
 	/**
 	 * Instance of a comment meta fields object.
 	 *
+	 * @since 4.7.0
 	 * @access protected
 	 * @var WP_REST_Comment_Meta_Fields
 	 */
 	protected $meta;
 
+	/**
+	 * Constructor.
+	 *
+	 * @since 4.7.0
+	 * @access public
+	 */
 	public function __construct() {
 		$this->namespace = 'wp/v2';
 		$this->rest_base = 'comments';
@@ -21,7 +39,10 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 	}
 
 	/**
-	 * Register the routes for the objects of the controller.
+	 * Registers the routes for the objects of the controller.
+	 *
+	 * @since 4.7.0
+	 * @access public
 	 */
 	public function register_routes() {
 
@@ -72,16 +93,20 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 	}
 
 	/**
-	 * Check if a given request has access to read comments
+	 * Checks if a given request has access to read comments.
 	 *
-	 * @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 WP_Error|bool True if the request has read access, error object otherwise.
 	 */
 	public function get_items_permissions_check( $request ) {
 
 		if ( ! empty( $request['post'] ) ) {
 			foreach ( (array) $request['post'] as $post_id ) {
 				$post = $this->get_post( $post_id );
+
 				if ( ! empty( $post_id ) && $post && ! $this->check_read_post_permission( $post ) ) {
 					return new WP_Error( 'rest_cannot_read_post', __( 'Sorry, you cannot read the post for this comment.' ), array( 'status' => rest_authorization_required_code() ) );
 				} elseif ( 0 === $post_id && ! current_user_can( 'moderate_comments' ) ) {
@@ -97,6 +122,7 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 		if ( ! current_user_can( 'edit_posts' ) ) {
 			$protected_params = array( 'author', 'author_exclude', 'karma', 'author_email', 'type', 'status' );
 			$forbidden_params = array();
+
 			foreach ( $protected_params as $param ) {
 				if ( 'status' === $param ) {
 					if ( 'approve' !== $request[ $param ] ) {
@@ -110,6 +136,7 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 					$forbidden_params[] = $param;
 				}
 			}
+
 			if ( ! empty( $forbidden_params ) ) {
 				return new WP_Error( 'rest_forbidden_param', sprintf( __( 'Query parameter not permitted: %s' ), implode( ', ', $forbidden_params ) ), array( 'status' => rest_authorization_required_code() ) );
 			}
@@ -119,20 +146,25 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 	}
 
 	/**
-	 * Get a list of comments.
+	 * Retrieves a list of comment items.
 	 *
-	 * @param  WP_REST_Request $request Full details about the request.
+	 * @since 4.7.0
-	 * @return WP_Error|WP_REST_Response
+	 * @access public
+	 *
+	 * @param WP_REST_Request $request Full details about the request.
+	 * @return WP_Error|WP_REST_Response Response object on success, or error object on failure.
 	 */
 	public function get_items( $request ) {
 
 		// Retrieve the list of registered collection query parameters.
 		$registered = $this->get_collection_params();
 
-		// This array defines mappings between public API query parameters whose
+		/*
-		// values are accepted as-passed, and their internal WP_Query parameter
+		 * This array defines mappings between public API query parameters whose
-		// name equivalents (some are the same). Only values which are also
+		 * values are accepted as-passed, and their internal WP_Query parameter
-		// present in $registered will be set.
+		 * name equivalents (some are the same). Only values which are also
+		 * present in $registered will be set.
+		 */
 		$parameter_mappings = array(
 			'author'         => 'author__in',
 			'author_email'   => 'author_email',
@@ -153,8 +185,10 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 
 		$prepared_args = array();
 
-		// For each known parameter which is both registered and present in the request,
+		/*
-		// set the parameter's value on the query $prepared_args.
+		 * For each known parameter which is both registered and present in the request,
+		 * set the parameter's value on the query $prepared_args.
+		 */
 		foreach ( $parameter_mappings as $api_param => $wp_param ) {
 			if ( isset( $registered[ $api_param ], $request[ $api_param ] ) ) {
 				$prepared_args[ $wp_param ] = $request[ $api_param ];
@@ -175,6 +209,7 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 		$prepared_args['no_found_rows'] = false;
 
 		$prepared_args['date_query'] = array();
+
 		// Set before into date query. Date query must be specified as an array of an array.
 		if ( isset( $registered['before'], $request['before'] ) ) {
 			$prepared_args['date_query'][0]['before'] = $request['before'];
@@ -190,9 +225,11 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 		}
 
 		/**
-		 * Filter arguments, before passing to WP_Comment_Query, when querying comments via the REST API.
+		 * Filters arguments, before passing to WP_Comment_Query, when querying comments via the REST API.
 		 *
-		 * @see https://developer.wordpress.org/reference/classes/wp_comment_query/
+		 * @since 4.7.0
+		 *
+		 * @link https://developer.wordpress.org/reference/classes/wp_comment_query/
 		 *
 		 * @param array           $prepared_args Array of arguments for WP_Comment_Query.
 		 * @param WP_REST_Request $request       The current request.
@@ -203,6 +240,7 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 		$query_result = $query->query( $prepared_args );
 
 		$comments = array();
+
 		foreach ( $query_result as $comment ) {
 			if ( ! $this->check_read_permission( $comment ) ) {
 				continue;
@@ -213,10 +251,12 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 		}
 
 		$total_comments = (int) $query->found_comments;
-		$max_pages = (int) $query->max_num_pages;
+		$max_pages      = (int) $query->max_num_pages;
+
 		if ( $total_comments < 1 ) {
-			// Out-of-bounds, run the query again without LIMIT for total count
+			// Out-of-bounds, run the query again without LIMIT for total count.
 			unset( $prepared_args['number'], $prepared_args['offset'] );
+
 			$query = new WP_Comment_Query;
 			$prepared_args['count'] = true;
 
@@ -229,17 +269,22 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 		$response->header( 'X-WP-TotalPages', $max_pages );
 
 		$base = add_query_arg( $request->get_query_params(), rest_url( sprintf( '%s/%s', $this->namespace, $this->rest_base ) ) );
+
 		if ( $request['page'] > 1 ) {
 			$prev_page = $request['page'] - 1;
+
 			if ( $prev_page > $max_pages ) {
 				$prev_page = $max_pages;
 			}
+
 			$prev_link = add_query_arg( 'page', $prev_page, $base );
 			$response->link_header( 'prev', $prev_link );
 		}
+
 		if ( $max_pages > $request['page'] ) {
 			$next_page = $request['page'] + 1;
 			$next_link = add_query_arg( 'page', $next_page, $base );
+
 			$response->link_header( 'next', $next_link );
 		}
 
@@ -247,10 +292,13 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 	}
 
 	/**
-	 * Check if a given request has access to read the comment
+	 * Checks if a given request has access to read the comment.
 	 *
-	 * @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 WP_Error|bool True if the request has read access for the item, error object otherwise.
 	 */
 	public function get_item_permissions_check( $request ) {
 		$id = (int) $request['id'];
@@ -279,10 +327,13 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 	}
 
 	/**
-	 * Get a comment.
+	 * Retrieves a comment.
 	 *
-	 * @param  WP_REST_Request $request Full details about the request.
+	 * @since 4.7.0
-	 * @return WP_Error|WP_REST_Response
+	 * @access public
+	 *
+	 * @param WP_REST_Request $request Full details about the request.
+	 * @return WP_Error|WP_REST_Response Response object on success, or error object on failure.
 	 */
 	public function get_item( $request ) {
 		$id = (int) $request['id'];
@@ -306,10 +357,13 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 	}
 
 	/**
-	 * Check if a given request has access to create a comment
+	 * Checks if a given request has access to create a comment.
 	 *
-	 * @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 WP_Error|bool True if the request has access to create items, error object otherwise.
 	 */
 	public function create_item_permissions_check( $request ) {
 
@@ -321,9 +375,11 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 		if ( isset( $request['author'] ) && get_current_user_id() !== $request['author'] && ! current_user_can( 'moderate_comments' ) ) {
 			return new WP_Error( 'rest_comment_invalid_author', __( 'Comment author invalid.' ), array( 'status' => rest_authorization_required_code() ) );
 		}
+
 		if ( isset( $request['karma'] ) && $request['karma'] > 0 && ! current_user_can( 'moderate_comments' ) ) {
 			return new WP_Error( 'rest_comment_invalid_karma', __( 'Sorry, you cannot set karma for comments.' ), array( 'status' => rest_authorization_required_code() ) );
 		}
+
 		if ( isset( $request['status'] ) && ! current_user_can( 'moderate_comments' ) ) {
 			return new WP_Error( 'rest_comment_invalid_status', __( 'Sorry, you cannot set status for comments.' ), array( 'status' => rest_authorization_required_code() ) );
 		}
@@ -354,10 +410,13 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 	}
 
 	/**
-	 * Create a comment.
+	 * Creates a comment.
 	 *
-	 * @param  WP_REST_Request $request Full details about the request.
+	 * @since 4.7.0
-	 * @return WP_Error|WP_REST_Response
+	 * @access public
+	 *
+	 * @param WP_REST_Request $request Full details about the request.
+	 * @return WP_Error|WP_REST_Response Response object on success, or error object on failure.
 	 */
 	public function create_item( $request ) {
 		if ( ! empty( $request['id'] ) ) {
@@ -365,26 +424,25 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 		}
 
 		$prepared_comment = $this->prepare_item_for_database( $request );
+
 		if ( is_wp_error( $prepared_comment ) ) {
 			return $prepared_comment;
 		}
 
-		/**
+		/*
 		 * Do not allow a comment to be created with an empty string for
-		 * comment_content.
+		 * comment_content. See wp_handle_comment_submission().
-		 * See `wp_handle_comment_submission()`.
 		 */
 		if ( '' === $prepared_comment['comment_content'] ) {
 			return new WP_Error( 'rest_comment_content_invalid', __( 'Comment content is invalid.' ), array( 'status' => 400 ) );
 		}
 
-		// Setting remaining values before wp_insert_comment so we can
+		// Setting remaining values before wp_insert_comment so we can use wp_allow_comment().
-		// use wp_allow_comment().
 		if ( ! isset( $prepared_comment['comment_date_gmt'] ) ) {
 			$prepared_comment['comment_date_gmt'] = current_time( 'mysql', true );
 		}
 
-		// Set author data if the user's logged in
+		// Set author data if the user's logged in.
 		$missing_author = empty( $prepared_comment['user_id'] )
 			&& empty( $prepared_comment['comment_author'] )
 			&& empty( $prepared_comment['comment_author_email'] )
@@ -392,21 +450,23 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 
 		if ( is_user_logged_in() && $missing_author ) {
 			$user = wp_get_current_user();
+
 			$prepared_comment['user_id'] = $user->ID;
 			$prepared_comment['comment_author'] = $user->display_name;
 			$prepared_comment['comment_author_email'] = $user->user_email;
 			$prepared_comment['comment_author_url'] = $user->user_url;
 		}
 
-		// Honor the discussion setting that requires a name and email address
+		// Honor the discussion setting that requires a name and email address of the comment author.
-		// of the comment author.
 		if ( get_option( 'require_name_email' ) ) {
 			if ( ! isset( $prepared_comment['comment_author'] ) && ! isset( $prepared_comment['comment_author_email'] ) ) {
 				return new WP_Error( 'rest_comment_author_data_required', __( 'Creating a comment requires valid author name and email values.' ), array( 'status' => 400 ) );
 			}
+
 			if ( ! isset( $prepared_comment['comment_author'] ) ) {
 				return new WP_Error( 'rest_comment_author_required', __( 'Creating a comment requires a valid author name.' ), array( 'status' => 400 ) );
 			}
+
 			if ( ! isset( $prepared_comment['comment_author_email'] ) ) {
 				return new WP_Error( 'rest_comment_author_email_required', __( 'Creating a comment requires a valid author email.' ), array( 'status' => 400 ) );
 			}
@@ -415,6 +475,7 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 		if ( ! isset( $prepared_comment['comment_author_email'] ) ) {
 			$prepared_comment['comment_author_email'] = '';
 		}
+
 		if ( ! isset( $prepared_comment['comment_author_url'] ) ) {
 			$prepared_comment['comment_author_url'] = '';
 		}
@@ -426,7 +487,7 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 		$prepared_comment['comment_approved'] = wp_allow_comment( $prepared_comment, true );
 
 		if ( is_wp_error( $prepared_comment['comment_approved'] ) ) {
-			$error_code = $prepared_comment['comment_approved']->get_error_code();
+			$error_code    = $prepared_comment['comment_approved']->get_error_code();
 			$error_message = $prepared_comment['comment_approved']->get_error_message();
 
 			if ( 'comment_duplicate' === $error_code ) {
@@ -441,52 +502,65 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 		}
 
 		/**
-		 * Filter a comment before it is inserted via the REST API.
+		 * Filters a comment before it is inserted via the REST API.
 		 *
-		 * Allows modification of the comment right before it is inserted via `wp_insert_comment`.
+		 * Allows modification of the comment right before it is inserted via wp_insert_comment().
 		 *
-		 * @param array           $prepared_comment The prepared comment data for `wp_insert_comment`.
+		 * @since 4.7.0
+		 *
+		 * @param array           $prepared_comment The prepared comment data for wp_insert_comment().
 		 * @param WP_REST_Request $request          Request used to insert the comment.
 		 */
 		$prepared_comment = apply_filters( 'rest_pre_insert_comment', $prepared_comment, $request );
 
 		$comment_id = wp_insert_comment( $prepared_comment );
+
 		if ( ! $comment_id ) {
 			return new WP_Error( 'rest_comment_failed_create', __( 'Creating comment failed.' ), array( 'status' => 500 ) );
 		}
 
 		if ( isset( $request['status'] ) ) {
 			$comment = get_comment( $comment_id );
+
 			$this->handle_status_param( $request['status'], $comment );
 		}
 
 		$schema = $this->get_item_schema();
+
 		if ( ! empty( $schema['properties']['meta'] ) && isset( $request['meta'] ) ) {
 			$meta_update = $this->meta->update_value( $request['meta'], $comment_id );
+
 			if ( is_wp_error( $meta_update ) ) {
 				return $meta_update;
 			}
 		}
 
 		$comment = get_comment( $comment_id );
+
 		$fields_update = $this->update_additional_fields_for_object( $comment, $request );
+
 		if ( is_wp_error( $fields_update ) ) {
 			return $fields_update;
 		}
 
 		$context = current_user_can( 'moderate_comments' ) ? 'edit' : 'view';
+
 		$request->set_param( 'context', $context );
+
 		$response = $this->prepare_item_for_response( $comment, $request );
 		$response = rest_ensure_response( $response );
+
 		$response->set_status( 201 );
 		$response->header( 'Location', rest_url( sprintf( '%s/%s/%d', $this->namespace, $this->rest_base, $comment_id ) ) );
 
 		/**
 		 * Fires after a comment is created or updated via the REST API.
 		 *
+		 * @since 4.7.0
+		 *
 		 * @param array           $comment  Comment as it exists in the database.
 		 * @param WP_REST_Request $request  The request sent to the API.
-		 * @param boolean         $creating True when creating a comment, false when updating.
+		 * @param bool            $creating True when creating a comment, false when updating.
 		 */
 		do_action( 'rest_insert_comment', $comment, $request, true );
 
@@ -494,10 +568,13 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 	}
 
 	/**
-	 * Check if a given request has access to update a comment
+	 * Checks if a given REST request has access to update a comment.
 	 *
-	 * @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 WP_Error|bool True if the request has access to update the item, error object otherwise.
 	 */
 	public function update_item_permissions_check( $request ) {
 
@@ -513,15 +590,19 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 	}
 
 	/**
-	 * Edit a comment
+	 * Updates a comment.
 	 *
-	 * @param  WP_REST_Request $request Full details about the request.
+	 * @since 4.7.0
-	 * @return WP_Error|WP_REST_Response
+	 * @access public
+	 *
+	 * @param WP_REST_Request $request Full details about the request.
+	 * @return WP_Error|WP_REST_Response Response object on success, or error object on failure.
 	 */
 	public function update_item( $request ) {
 		$id = (int) $request['id'];
 
 		$comment = get_comment( $id );
+
 		if ( empty( $comment ) ) {
 			return new WP_Error( 'rest_comment_invalid_id', __( 'Invalid comment id.' ), array( 'status' => 404 ) );
 		}
@@ -531,6 +612,7 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 		}
 
 		$prepared_args = $this->prepare_item_for_database( $request );
+
 		if ( is_wp_error( $prepared_args ) ) {
 			return $prepared_args;
 		}
@@ -538,6 +620,7 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 		if ( empty( $prepared_args ) && isset( $request['status'] ) ) {
 			// Only the comment status is being changed.
 			$change = $this->handle_status_param( $request['status'], $comment );
+
 			if ( ! $change ) {
 				return new WP_Error( 'rest_comment_failed_edit', __( 'Updating comment status failed.' ), array( 'status' => 500 ) );
 			}
@@ -549,6 +632,7 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 			$prepared_args['comment_ID'] = $id;
 
 			$updated = wp_update_comment( $prepared_args );
+
 			if ( 0 === $updated ) {
 				return new WP_Error( 'rest_comment_failed_edit', __( 'Updating comment failed.' ), array( 'status' => 500 ) );
 			}
@@ -559,20 +643,25 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 		}
 
 		$schema = $this->get_item_schema();
+
 		if ( ! empty( $schema['properties']['meta'] ) && isset( $request['meta'] ) ) {
 			$meta_update = $this->meta->update_value( $request['meta'], $id );
+
 			if ( is_wp_error( $meta_update ) ) {
 				return $meta_update;
 			}
 		}
 
 		$comment = get_comment( $id );
+
 		$fields_update = $this->update_additional_fields_for_object( $comment, $request );
+
 		if ( is_wp_error( $fields_update ) ) {
 			return $fields_update;
 		}
 
 		$request->set_param( 'context', 'edit' );
+
 		$response = $this->prepare_item_for_response( $comment, $request );
 
 		/* This action is documented in lib/endpoints/class-wp-rest-comments-controller.php */
@@ -582,17 +671,22 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 	}
 
 	/**
-	 * Check if a given request has access to delete a comment
+	 * Checks if a given request has access to delete a comment.
 	 *
-	 * @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 WP_Error|bool True if the request has access to delete the item, error object otherwise.
 	 */
 	public function delete_item_permissions_check( $request ) {
-		$id = (int) $request['id'];
+		$id      = (int) $request['id'];
 		$comment = get_comment( $id );
+
 		if ( ! $comment ) {
 			return new WP_Error( 'rest_comment_invalid_id', __( 'Invalid comment id.' ), array( 'status' => 404 ) );
 		}
+
 		if ( ! $this->check_edit_permission( $comment ) ) {
 			return new WP_Error( 'rest_cannot_delete', __( 'Sorry, you can not delete this comment.' ), array( 'status' => rest_authorization_required_code() ) );
 		}
@@ -600,37 +694,44 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 	}
 
 	/**
-	 * Delete a comment.
+	 * Deletes a comment.
 	 *
-	 * @param  WP_REST_Request $request Full details about the request.
+	 * @since 4.7.0
-	 * @return WP_Error|WP_REST_Response
+	 * @access public
+	 *
+	 * @param WP_REST_Request $request Full details about the request.
+	 * @return WP_Error|WP_REST_Response Response object on success, or error object on failure.
 	 */
 	public function delete_item( $request ) {
-		$id = (int) $request['id'];
+		$id    = (int) $request['id'];
 		$force = isset( $request['force'] ) ? (bool) $request['force'] : false;
 
 		$comment = get_comment( $id );
+
 		if ( empty( $comment ) ) {
 			return new WP_Error( 'rest_comment_invalid_id', __( 'Invalid comment id.' ), array( 'status' => 404 ) );
 		}
 
 		/**
-		 * Filter whether a comment is trashable.
+		 * Filters whether a comment can be trashed.
 		 *
 		 * Return false to disable trash support for the post.
 		 *
-		 * @param boolean $supports_trash Whether the post type support trashing.
+		 * @since 4.7.0
+		 *
+		 * @param bool    $supports_trash Whether the post type support trashing.
 		 * @param WP_Post $comment        The comment object being considered for trashing support.
 		 */
 		$supports_trash = apply_filters( 'rest_comment_trashable', ( EMPTY_TRASH_DAYS > 0 ), $comment );
 
 		$request->set_param( 'context', 'edit' );
+
 		$response = $this->prepare_item_for_response( $comment, $request );
 
 		if ( $force ) {
 			$result = wp_delete_comment( $comment->comment_ID, true );
 		} else {
-			// If we don't support trashing for this type, error out
+			// If this type doesn't support trashing, error out.
 			if ( ! $supports_trash ) {
 				return new WP_Error( 'rest_trash_not_supported', __( 'The comment does not support trashing.' ), array( 'status' => 501 ) );
 			}
@@ -649,7 +750,9 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 		/**
 		 * Fires after a comment is deleted via the REST API.
 		 *
-		 * @param object           $comment  The deleted comment data.
+		 * @since 4.7.0
+		 *
+		 * @param WP_Comment       $comment  The deleted comment data.
 		 * @param WP_REST_Response $response The response returned from the API.
 		 * @param WP_REST_Request  $request  The request sent to the API.
 		 */
@@ -659,11 +762,14 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 	}
 
 	/**
-	 * Prepare a single comment output for response.
+	 * Prepares a single comment output for response.
 	 *
-	 * @param  object          $comment Comment object.
+	 * @since 4.7.0
-	 * @param  WP_REST_Request $request Request object.
+	 * @access public
-	 * @return WP_REST_Response $response
+	 *
+	 * @param WP_Comment      $comment Comment object.
+	 * @param WP_REST_Request $request Request object.
+	 * @return WP_REST_Response Response object.
 	 */
 	public function prepare_item_for_response( $comment, $request ) {
 		$data = array(
@@ -679,6 +785,7 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 			'date'               => mysql_to_rfc3339( $comment->comment_date ),
 			'date_gmt'           => mysql_to_rfc3339( $comment->comment_date_gmt ),
 			'content'            => array(
+				/** This filter is documented in wp-includes/comment-template.php */
 				'rendered' => apply_filters( 'comment_text', $comment->comment_content, $comment ),
 				'raw'      => $comment->comment_content,
 			),
@@ -699,30 +806,35 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 		}
 
 		$context = ! empty( $request['context'] ) ? $request['context'] : 'view';
-		$data = $this->add_additional_fields_to_object( $data, $request );
+		$data    = $this->add_additional_fields_to_object( $data, $request );
-		$data = $this->filter_response_by_context( $data, $context );
+		$data    = $this->filter_response_by_context( $data, $context );
 
-		// Wrap the data in a response object
+		// Wrap the data in a response object.
 		$response = rest_ensure_response( $data );
 
 		$response->add_links( $this->prepare_links( $comment ) );
 
 		/**
-		 * Filter a comment returned from the API.
+		 * Filters a comment returned from the API.
 		 *
 		 * Allows modification of the comment right before it is returned.
 		 *
-		 * @param WP_REST_Response  $response   The response object.
+		 * @since 4.7.0
-		 * @param object            $comment    The original comment object.
+		 *
-		 * @param WP_REST_Request   $request    Request used to generate the response.
+		 * @param WP_REST_Response  $response The response object.
+		 * @param WP_Comment        $comment  The original comment object.
+		 * @param WP_REST_Request   $request  Request used to generate the response.
 		 */
 		return apply_filters( 'rest_prepare_comment', $response, $comment, $request );
 	}
 
 	/**
-	 * Prepare links for the request.
+	 * Prepares links for the request.
 	 *
-	 * @param object $comment Comment object.
+	 * @since 4.7.0
+	 * @access protected
+	 *
+	 * @param WP_Comment $comment Comment object.
 	 * @return array Links for the given comment.
 	 */
 	protected function prepare_links( $comment ) {
@@ -744,6 +856,7 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 
 		if ( 0 !== (int) $comment->comment_post_ID ) {
 			$post = $this->get_post( $comment->comment_post_ID );
+
 			if ( ! empty( $post->ID ) ) {
 				$obj = get_post_type_object( $post->post_type );
 				$base = ! empty( $obj->rest_base ) ? $obj->rest_base : $obj->name;
@@ -764,9 +877,16 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 		}
 
 		// Only grab one comment to verify the comment has children.
-		$comment_children = $comment->get_children( array( 'number' => 1, 'count' => true ) );
+		$comment_children = $comment->get_children( array(
+			'number' => 1,
+			'count'  => true
+		) );
+
 		if ( ! empty( $comment_children ) ) {
-			$args = array( 'parent' => $comment->comment_ID );
+			$args = array(
+				'parent' => $comment->comment_ID
+			);
+
 			$rest_url = add_query_arg( $args, rest_url( $this->namespace . '/' . $this->rest_base ) );
 
 			$links['children'] = array(
@@ -778,10 +898,13 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 	}
 
 	/**
-	 * Prepend internal property prefix to query parameters to match our response fields.
+	 * Prepends internal property prefix to query parameters to match our response fields.
 	 *
-	 * @param  string $query_param
+	 * @since 4.7.0
-	 * @return string $normalized
+	 * @access protected
+	 *
+	 * @param string $query_param Query parameter.
+	 * @return string The normalized query parameter.
 	 */
 	protected function normalize_query_param( $query_param ) {
 		$prefix = 'comment_';
@@ -808,10 +931,13 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 	}
 
 	/**
-	 * Check comment_approved to set comment status for single comment output.
+	 * Checks comment_approved to set comment status for single comment output.
 	 *
-	 * @param  string|int $comment_approved
+	 * @since 4.7.0
-	 * @return string     $status
+	 * @access protected
+	 *
+	 * @param string|int $comment_approved comment status.
+	 * @return string Comment status.
 	 */
 	protected function prepare_status_response( $comment_approved ) {
 
@@ -837,15 +963,18 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 	}
 
 	/**
-	 * Prepare a single comment to be inserted into the database.
+	 * Prepares a single comment to be inserted into the database.
 	 *
-	 * @param  WP_REST_Request $request Request object.
+	 * @since 4.7.0
-	 * @return array|WP_Error  $prepared_comment
+	 * @access protected
+	 *
+	 * @param WP_REST_Request $request Request object.
+	 * @return array|WP_Error Prepared comment, otherwise WP_Error object.
 	 */
 	protected function prepare_item_for_database( $request ) {
 		$prepared_comment = array();
 
-		/**
+		/*
 		 * Allow the comment_content to be set via the 'content' or
 		 * the 'content.raw' properties of the Request object.
 		 */
@@ -865,6 +994,7 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 
 		if ( isset( $request['author'] ) ) {
 			$user = new WP_User( $request['author'] );
+
 			if ( $user->exists() ) {
 				$prepared_comment['user_id'] = $user->ID;
 				$prepared_comment['comment_author'] = $user->display_name;
@@ -918,17 +1048,29 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 			}
 		}
 
-		// Require 'comment_content' unless only the 'comment_status' is being
+		// Require 'comment_content' unless only the 'comment_status' is being updated.
-		// updated.
 		if ( ! empty( $prepared_comment ) && ! isset( $prepared_comment['comment_content'] ) ) {
 			return new WP_Error( 'rest_comment_content_required', __( 'Missing comment content.' ), array( 'status' => 400 ) );
 		}
 
+		/**
+		 * Filters a comment after it is prepared for the database.
+		 *
+		 * Allows modification of the comment right after it is prepared for the database.
+		 *
+		 * @since 4.7.0
+		 *
+		 * @param array           $prepared_comment The prepared comment data for `wp_insert_comment`.
+		 * @param WP_REST_Request $request          The current request.
+		 */
 		return apply_filters( 'rest_preprocess_comment', $prepared_comment, $request );
 	}
 
 	/**
-	 * Get the Comment's schema, conforming to JSON Schema
+	 * Retrieves the comment's schema, conforming to JSON Schema.
+	 *
+	 * @since 4.7.0
+	 * @access public
 	 *
 	 * @return array
 	 */
@@ -1091,9 +1233,12 @@ class WP_REST_Comments_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 Comments collection parameters.
 	 */
 	public function get_collection_params() {
 		$query_params = parent::get_collection_params();
@@ -1106,16 +1251,19 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 			'format'            => 'date-time',
 			'validate_callback' => 'rest_validate_request_arg',
 		);
+
 		$query_params['author'] = array(
 			'description'       => __( 'Limit result set to comments assigned to specific user ids. Requires authorization.' ),
 			'sanitize_callback' => 'wp_parse_id_list',
 			'type'              => 'array',
 		);
+
 		$query_params['author_exclude'] = array(
 			'description'       => __( 'Ensure result set excludes comments assigned to specific user ids. Requires authorization.' ),
 			'sanitize_callback' => 'wp_parse_id_list',
 			'type'              => 'array',
 		);
+
 		$query_params['author_email'] = array(
 			'default'           => null,
 			'description'       => __( 'Limit result set to that from a specific author email. Requires authorization.' ),
@@ -1123,24 +1271,28 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 			'sanitize_callback' => 'sanitize_email',
 			'type'              => 'string',
 		);
+
 		$query_params['before'] = array(
 			'description'       => __( 'Limit response to resources published before a given ISO8601 compliant date.' ),
 			'type'              => 'string',
 			'format'            => 'date-time',
 			'validate_callback' => 'rest_validate_request_arg',
 		);
+
 		$query_params['exclude'] = array(
 			'description'        => __( 'Ensure result set excludes specific ids.' ),
 			'type'               => 'array',
 			'default'            => array(),
 			'sanitize_callback'  => 'wp_parse_id_list',
 		);
+
 		$query_params['include'] = array(
 			'description'        => __( 'Limit result set to specific ids.' ),
 			'type'               => 'array',
 			'default'            => array(),
 			'sanitize_callback'  => 'wp_parse_id_list',
 		);
+
 		$query_params['karma'] = array(
 			'default'           => null,
 			'description'       => __( 'Limit result set to that of a particular comment karma. Requires authorization.' ),
@@ -1148,12 +1300,14 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 			'type'              => 'integer',
 			'validate_callback'  => 'rest_validate_request_arg',
 		);
+
 		$query_params['offset'] = array(
 			'description'        => __( 'Offset the result set by a specific number of comments.' ),
 			'type'               => 'integer',
 			'sanitize_callback'  => 'absint',
 			'validate_callback'  => 'rest_validate_request_arg',
 		);
+
 		$query_params['order']      = array(
 			'description'           => __( 'Order sort attribute ascending or descending.' ),
 			'type'                  => 'string',
@@ -1165,6 +1319,7 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 				'desc',
 			),
 		);
+
 		$query_params['orderby']    = array(
 			'description'           => __( 'Sort collection by object attribute.' ),
 			'type'                  => 'string',
@@ -1181,24 +1336,28 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 				'type',
 			),
 		);
+
 		$query_params['parent'] = array(
 			'default'           => array(),
 			'description'       => __( 'Limit result set to resources of specific parent ids.' ),
 			'sanitize_callback' => 'wp_parse_id_list',
 			'type'              => 'array',
 		);
+
 		$query_params['parent_exclude'] = array(
 			'default'           => array(),
 			'description'       => __( 'Ensure result set excludes specific parent ids.' ),
 			'sanitize_callback' => 'wp_parse_id_list',
 			'type'              => 'array',
 		);
+
 		$query_params['post']   = array(
 			'default'           => array(),
 			'description'       => __( 'Limit result set to resources assigned to specific post ids.' ),
 			'type'              => 'array',
 			'sanitize_callback' => 'wp_parse_id_list',
 		);
+
 		$query_params['status'] = array(
 			'default'           => 'approve',
 			'description'       => __( 'Limit result set to comments assigned a specific status. Requires authorization.' ),
@@ -1206,6 +1365,7 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 			'type'              => 'string',
 			'validate_callback' => 'rest_validate_request_arg',
 		);
+
 		$query_params['type'] = array(
 			'default'           => 'comment',
 			'description'       => __( 'Limit result set to comments assigned a specific type. Requires authorization.' ),
@@ -1213,15 +1373,19 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 			'type'              => 'string',
 			'validate_callback' => 'rest_validate_request_arg',
 		);
+
 		return $query_params;
 	}
 
 	/**
-	 * Set the comment_status of a given comment object when creating or updating a comment.
+	 * Sets the comment_status of a given comment object when creating or updating a comment.
 	 *
-	 * @param string|int $new_status
+	 * @since 4.7.0
-	 * @param object     $comment
+	 * @access protected
-	 * @return boolean   $changed
+	 *
+	 * @param string|int $new_status New comment status.
+	 * @param WP_Comment $comment    Comment data.
+	 * @return bool Whether the status was changed.
 	 */
 	protected function handle_status_param( $new_status, $comment ) {
 		$old_status = wp_get_comment_status( $comment->comment_ID );
@@ -1261,12 +1425,15 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 	}
 
 	/**
-	 * Check if we can read a post.
+	 * Checks if the post can be read.
 	 *
 	 * Correctly handles posts with the inherit status.
 	 *
-	 * @param  WP_Post $post Post Object.
+	 * @since 4.7.0
-	 * @return boolean Can we read it?
+	 * @access protected
+	 *
+	 * @param WP_Post $post Post Object.
+	 * @return bool Whether post can be read.
 	 */
 	protected function check_read_post_permission( $post ) {
 		$posts_controller = new WP_REST_Posts_Controller( $post->post_type );
@@ -1275,10 +1442,13 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 	}
 
 	/**
-	 * Check if we can read a comment.
+	 * Checks if the comment can be read.
 	 *
-	 * @param  object  $comment Comment object.
+	 * @since 4.7.0
-	 * @return boolean Can we read it?
+	 * @access protected
+	 *
+	 * @param WP_Comment $comment Comment object.
+	 * @return bool Whether the comment can be read.
 	 */
 	protected function check_read_permission( $comment ) {
 		if ( ! empty( $comment->comment_post_ID ) ) {
@@ -1306,10 +1476,13 @@ class WP_REST_Comments_Controller extends WP_REST_Controller {
 	}
 
 	/**
-	 * Check if we can edit or delete a comment.
+	 * Checks if a comment can be edited or deleted.
 	 *
-	 * @param  object  $comment Comment object.
+	 * @since 4.7.0
-	 * @return boolean Can we edit or delete it?
+	 * @access protected
+	 *
+	 * @param object $comment Comment object.
+	 * @return bool Whether the comment can be edited or deleted.
 	 */
 	protected function check_edit_permission( $comment ) {
 		if ( 0 === (int) get_current_user_id() ) {