Ticket #44362: 44362.diff

src/js/_enqueues/admin/link.js

@@ -1 +1 @@
 /* global postboxes, deleteUserSetting, setUserSetting, getUserSetting */
 
+/**
+ * Binds to the document ready event.
+ *
+ * @since 2.5.0
+ *
+ * @param {jQuery} $ The jQuery object.
+ */
 jQuery(document).ready( function($) {
 
         var newCat, noSyncChecks = false, syncChecks, catAddAfter;
@@ -8 +15 @@
         // postboxes
         postboxes.add_postbox_toggles('link');
 
-        // category tabs
+        /**
+         * Adds event that opens a particular category tab.
+         *
+         * @listens $('#category-tabs a'):click
+         *
+         * @param {Event} event The event object.
+         * @returns {Boolean} False, prevents regular link functionality.
+         */
         $('#category-tabs a').click(function(){
                 var t = $(this).attr('href');
                 $(this).parent().addClass('tabs').siblings('li').removeClass('tabs');
@@ -25 +39 @@
 
         // Ajax Cat
         newCat = $('#newcat').one( 'focus', function() { $(this).val( '' ).removeClass( 'form-input-tip' ); } );
+
+        /**
+         * After adding a new category, focus on the category add input field.
+         *
+         * @listens $('#link-category-add-submit'):click
+         *
+         * @return {void}
+         */
         $('#link-category-add-submit').click( function() { newCat.focus(); } );
+
+        /**
+         * Syncronize category checkboxes.
+         *
+         * @return {void}
+         */
         syncChecks = function() {
                 if ( noSyncChecks )
                         return;
@@ -35 +63 @@
                 noSyncChecks = false;
         };
 
+        /**
+         * Callback that's run after an item got added to the list.
+         *
+         * @param {XML} r Raw response returned from the server.
+         * @param {Object} s List manager configuration object; settings for the Ajax request.
+         *
+         * @return {void}
+         */
         catAddAfter = function( r, s ) {
                 $(s.what + ' response_data', r).each( function() {
                         var t = $($(this).text());
@@ -46 +82 @@
                 } );
         };
 
+        /**
+         * List manager.
+         *
+         * @param {Object} List manager configuration object.
+         *
+         * @see wp-includes/js/wp-lists.js
+         *
+         * @type {wpList}
+         */
         $('#categorychecklist').wpList( {
+                // CSS class name for alternate styling.
                 alt: '',
+
+                // The type of list.
                 what: 'link-category',
+
+                // ID of the element the parsed Ajax response will be stored in.
                 response: 'category-ajax-response',
+
+                // Callback that's run after an item got added to the list.
                 addAfter: catAddAfter
         } );
 
+        /**
+         * Delete the user setting regarding which category tab should be shown.
+         *
+         * @listens $('a[href="#categories-all"]'):click
+         *
+         * @return {void}
+         */
         $('a[href="#categories-all"]').click(function(){deleteUserSetting('cats');});
+
+        /**
+         * Set the user setting regarding which category tab should be shown to display
+         * popular categories.
+         *
+         * @listens $('a[href="#categories-pop"]'):click
+         *
+         * @return {void}
+         */
         $('a[href="#categories-pop"]').click(function(){setUserSetting('cats','pop');});
+
         if ( 'pop' == getUserSetting('cats') )
                 $('a[href="#categories-pop"]').click();
 
+        /**
+         * Adds event that shows the interface controls to add a new category.
+         *
+         * @listens $('#category-add-toggle'):click
+         *
+         * @param {Event} event The event object.
+         * @returns {Boolean} False, prevents regular link functionality.
+         */
         $('#category-add-toggle').click( function() {
                 $(this).parents('div:first').toggleClass( 'wp-hidden-children' );
                 $('#category-tabs a[href="#categories-all"]').click();