REST API: Always fire the rest_insert_* actions after the related object is updated or inserted.

Brings consistency to the `rest_insert_*` actions. Also includes some shuffling and clean-up as well including:
- Ensure we are passing the most current `$post` and `$user` objects to the `update_additional_fields_for_object()` callbacks.
- Changes the function signature of `handle_status_param()` in the Comments controller to accept just the comment_id as the 2nd parameter, instead of a full WP_Comment object. Only the comment_id is needed in the method, this avoids having to include another `get_comment()` call. 
- Renames a variable in the `create_item()` method of the Posts controller from `$post` -> `$prepared_post` to be more explicit.
- Minor fixes/clarifications to the rest_insert_* hook docs

Props rachelbaker, joehoyle
Fixes #38905.

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

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

@@ -155,6 +155,18 @@ class WP_REST_Attachments_Controller extends WP_REST_Posts_Controller {
 
 		$attachment = get_post( $id );
 
+		/**
+		 * Fires after a single attachment is created or updated via the REST API.
+		 *
+		 * @since 4.7.0
+		 *
+		 * @param WP_Post         $attachment Inserted or updated attachment
+		 *                                    object.
+		 * @param WP_REST_Request $request    The request sent to the API.
+		 * @param bool            $creating   True when creating an attachment, false when updating.
+		 */
+		do_action( 'rest_insert_attachment', $attachment, $request, true );
+
 		// Include admin functions to get access to wp_generate_attachment_metadata().
 		require_once ABSPATH . 'wp-admin/includes/admin.php';
 
@@ -176,17 +188,6 @@ class WP_REST_Attachments_Controller extends WP_REST_Posts_Controller {
 		$response->set_status( 201 );
 		$response->header( 'Location', rest_url( sprintf( '%s/%s/%d', $this->namespace, $this->rest_base, $id ) ) );
 
-		/**
-		 * Fires after a single attachment is created or updated via the REST API.
-		 *
-		 * @since 4.7.0
-		 *
-		 * @param object          $attachment Inserted attachment.
-		 * @param WP_REST_Request $request    The request sent to the API.
-		 * @param bool            $creating   True when creating an attachment, false when updating.
-		 */
-		do_action( 'rest_insert_attachment', $attachment, $request, true );
-
 		return $response;
 	}
 
@@ -219,6 +220,9 @@ class WP_REST_Attachments_Controller extends WP_REST_Posts_Controller {
 
 		$attachment = get_post( $request['id'] );
 
+		/* This action is documented in wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php */
+		do_action( 'rest_insert_attachment', $data, $request, false );
+
 		$fields_update = $this->update_additional_fields_for_object( $attachment, $request );
 
 		if ( is_wp_error( $fields_update ) ) {
@@ -229,9 +233,6 @@ class WP_REST_Attachments_Controller extends WP_REST_Posts_Controller {
 		$response = $this->prepare_item_for_response( $attachment, $request );
 		$response = rest_ensure_response( $response );
 
-		/* This action is documented in wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php */
-		do_action( 'rest_insert_attachment', $data, $request, false );
-
 		return $response;
 	}