From 46cbfc405fb71393d60372c1181bb3fc735ed4e1 Mon Sep 17 00:00:00 2001
From: atimmer <atimmer@git.wordpress.org>
Date: Mon, 11 Dec 2017 16:27:51 +0000
Subject: [PATCH] Docs: Improve JS Docs for `custom-header.js`.

The `custom-header.js` file is only used on the `wp-admin/themes.php?page=custom-header` page. As that page is no longer linked from the UI the functions in the file are marked deprecated.

Props nicollle, jipmoors, diedeexterkate.
Fixes #42678.

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


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

diff --git a/wp-admin/js/custom-header.js b/wp-admin/js/custom-header.js
index ce224e448b..ffe4623540 100644
--- a/wp-admin/js/custom-header.js
+++ b/wp-admin/js/custom-header.js
@@ -1,12 +1,24 @@
 /* global isRtl */
+
+/**
+ * @summary Initializes the custom header selection page.
+ *
+ * @since 3.5.0
+ *
+ * @global
+ * @name Global
+ *
+ * @deprecated 4.1.0 The page this is used on is never linked to from the UI.
+ *             Setting a custom header is completely handled by the Customizer.
+ */
 (function($) {
 	var frame;
 
 	$( function() {
-		// Fetch available headers and apply jQuery.masonry
-		// once the images have loaded.
+		// Fetch available headers.
 		var $headers = $('.available-headers');
 
+		// Apply jQuery.masonry once the images have loaded.
 		$headers.imagesLoaded( function() {
 			$headers.masonry({
 				itemSelector: '.default-header',
@@ -14,7 +26,15 @@
 			});
 		});
 
-		// Build the choose from library frame.
+		/**
+		 * @summary Opens the 'choose from library' frame and creates it if it doesn't
+		 *          exist.
+		 *
+		 * @since 3.5.0
+		 * @deprecated 4.1.0
+		 *
+		 * @returns {void}
+		 */
 		$('#choose-from-library-link').click( function( event ) {
 			var $el = $(this);
 			event.preventDefault();
@@ -45,7 +65,14 @@
 				}
 			});
 
-			// When an image is selected, run a callback.
+			/**
+			 * @summary Updates the window location to include the selected attachment.
+			 *
+			 * @since 3.5.0
+			 * @deprecated 4.1.0
+			 *
+			 * @returns {void}
+			 */
 			frame.on( 'select', function() {
 				// Grab the selected attachment.
 				var attachment = frame.state().get('selection').first(),
diff --git a/wp-includes/version.php b/wp-includes/version.php
index 6a79b630f5..eda548dabe 100644
--- a/wp-includes/version.php
+++ b/wp-includes/version.php
@@ -4,7 +4,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '5.0-alpha-42384';
+$wp_version = '5.0-alpha-42385';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.