From bd990d7c4e222e08a522d062fd911ae72c37b3e5 Mon Sep 17 00:00:00 2001
From: Weston Ruter <weston@xwp.co>
Date: Fri, 19 May 2017 03:53:43 +0000
Subject: [PATCH] Docs: Add missing `@since` tags and phpdoc descriptions to
 the `Custom_Image_Header` class.

Amends [27497].
Props tejas5989, riddhiehta02, westonruter.
See #21785.
Fixes #40231.

Built from https://develop.svn.wordpress.org/trunk@40788


git-svn-id: http://core.svn.wordpress.org/trunk@40646 1a063a9b-81f0-0310-95a4-ce76da25c4cd
---
 wp-admin/custom-header.php | 31 +++++++++++++++++++++++++------
 wp-includes/version.php    |  2 +-
 2 files changed, 26 insertions(+), 7 deletions(-)

diff --git a/wp-admin/custom-header.php b/wp-admin/custom-header.php
index 5cc64ef7bf..b9aecf2485 100644
--- a/wp-admin/custom-header.php
+++ b/wp-admin/custom-header.php
@@ -42,7 +42,7 @@ class Custom_Image_Header {
 
 	/**
 	 * Used to trigger a success message when settings updated and set to true.
- 	 *
+	 *
 	 * @since 3.0.0
 	 * @access private
 	 * @var bool
@@ -1097,6 +1097,8 @@ wp_nonce_field( 'custom-header-options', '_wpnonce-custom-header-options' ); ?>
 	/**
 	 * Calculate width and height based on what the currently selected theme supports.
 	 *
+	 * @since 3.9.0
+	 *
 	 * @param array $dimensions
 	 * @return array dst_height and dst_width of header image.
 	 */
@@ -1147,9 +1149,10 @@ wp_nonce_field( 'custom-header-options', '_wpnonce-custom-header-options' ); ?>
 	/**
 	 * Create an attachment 'object'.
 	 *
+	 * @since 3.9.0
+	 *
 	 * @param string $cropped              Cropped image URL.
 	 * @param int    $parent_attachment_id Attachment ID of parent image.
-	 *
 	 * @return array Attachment object.
 	 */
 	final public function create_attachment_object( $cropped, $parent_attachment_id ) {
@@ -1174,9 +1177,10 @@ wp_nonce_field( 'custom-header-options', '_wpnonce-custom-header-options' ); ?>
 	/**
 	 * Insert an attachment and its metadata.
 	 *
+	 * @since 3.9.0
+	 *
 	 * @param array  $object  Attachment object.
 	 * @param string $cropped Cropped image URL.
-	 *
 	 * @return int Attachment ID.
 	 */
 	final public function insert_attachment( $object, $cropped ) {
@@ -1199,6 +1203,8 @@ wp_nonce_field( 'custom-header-options', '_wpnonce-custom-header-options' ); ?>
 	/**
 	 * Gets attachment uploaded by Media Manager, crops it, then saves it as a
 	 * new object. Returns JSON-encoded object details.
+	 *
+	 * @since 3.9.0
 	 */
 	public function ajax_header_crop() {
 		check_ajax_referer( 'image_editor-' . $_POST['id'], 'nonce' );
@@ -1257,6 +1263,8 @@ wp_nonce_field( 'custom-header-options', '_wpnonce-custom-header-options' ); ?>
 	 *
 	 * Triggered when the user tries adds a new header image from the
 	 * Media Manager, even if s/he doesn't save that change.
+	 *
+	 * @since 3.9.0
 	 */
 	public function ajax_header_add() {
 		check_ajax_referer( 'header-add', 'nonce' );
@@ -1283,6 +1291,8 @@ wp_nonce_field( 'custom-header-options', '_wpnonce-custom-header-options' ); ?>
 	 *
 	 * Triggered when the user clicks the overlay "X" button next to each image
 	 * choice in the Customizer's Header tool.
+	 *
+	 * @since 3.9.0
 	 */
 	public function ajax_header_remove() {
 		check_ajax_referer( 'header-remove', 'nonce' );
@@ -1304,8 +1314,11 @@ wp_nonce_field( 'custom-header-options', '_wpnonce-custom-header-options' ); ?>
 	}
 
 	/**
+	 * Updates the last-used postmeta on a header image attachment after saving a new header image via the Customizer.
 	 *
-	 * @param WP_Customize_Manager $wp_customize
+	 * @since 3.9.0
+	 *
+	 * @param WP_Customize_Manager $wp_customize Customize manager.
 	 */
 	public function customize_set_last_used( $wp_customize ) {
 		$data = $wp_customize->get_setting( 'header_image_data' )->post_value();
@@ -1320,8 +1333,11 @@ wp_nonce_field( 'custom-header-options', '_wpnonce-custom-header-options' ); ?>
 	}
 
 	/**
+	 * Gets the details of default header images if defined.
 	 *
-	 * @return array
+	 * @since 3.9.0
+	 *
+	 * @return array Default header images.
 	 */
 	public function get_default_header_images() {
 		$this->process_default_headers();
@@ -1360,8 +1376,11 @@ wp_nonce_field( 'custom-header-options', '_wpnonce-custom-header-options' ); ?>
 	}
 
 	/**
+	 * Gets the previously uploaded header images.
 	 *
-	 * @return array
+	 * @since 3.9.0
+	 *
+	 * @return array Uploaded header images.
 	 */
 	public function get_uploaded_header_images() {
 		$header_images = get_uploaded_header_images();
diff --git a/wp-includes/version.php b/wp-includes/version.php
index e54922d3ee..af662bf164 100644
--- a/wp-includes/version.php
+++ b/wp-includes/version.php
@@ -4,7 +4,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '4.8-beta1-40787';
+$wp_version = '4.8-beta1-40788';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.