Changeset 42385

Timestamp:

12/11/2017 04:26:59 PM (9 years ago)

Author:

atimmer

Message:

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.

File:

• trunk/src/wp-admin/js/custom-header.js (modified) (3 diffs)

trunk/src/wp-admin/js/custom-header.js

@@ -1 +1 @@
 /* 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({
@@ -15 +27 @@
                 });
 
-                // 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);
@@ -46 +66 @@
                         });
 
-                        // 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.