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.


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

src/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(),