Ticket #42679: common.diff

src/wp-admin/js/common.js

@@ -1 +1 @@
 /* global setUserSetting, ajaxurl, commonL10n, alert, confirm, pagenow */
 var showNotice, adminMenu, columns, validateForm, screenMeta;
+/**
+ *  @summary Adds common WordPress functionality to the window.
+ *
+ *  @param {jQuery} $        jQuery object.
+ *  @param {Object} window   The window object.
+ *  @param {mixed} undefined Unused.
+ */
 ( function( $, window, undefined ) {
         var $document = $( document ),
                 $window = $( window ),
                 $body = $( document.body );
 
-// Removed in 3.3.
-// (perhaps) needed for back-compat
+/**
+ * @summary Removed in 3.3.0, needed for back-compatibility.
+ *
+ * @since 2.7.0
+ * @deprecated 3.3.0
+ */
 adminMenu = {
         init : function() {},
         fold : function() {},
@@ -15 +26 @@
         favorites : function() {}
 };
 
-// show/hide/save table columns
+// Show/hide/save table columns.
 columns = {
+        /**
+         * @summary Initializes the column toggles in the screen options.
+         *
+         * Binds an onClick event to the checkboxes to show or hide the table columns
+         * based on their toggled state. And persists the toggled state.
+         *
+         * @since 2.7.0
+         *
+         * @returns {void}
+         */
         init : function() {
                 var that = this;
                 $('.hide-column-tog', '#adv-settings').click( function() {
@@ -29 +50 @@
                         columns.saveManageColumnsState();
                 });
         },
-
+        /**
+         * @summary Saves the toggled state for the columns.
+         *
+         * Saves whether the columns should be shown or hidden on a page.
+         *
+         * @since 3.0.0
+         *
+         * @returns {void}
+         */
         saveManageColumnsState : function() {
                 var hidden = this.hidden();
                 $.post(ajaxurl, {
@@ -40 +69 @@
                 });
         },
 
+        /**
+         * @summary Makes a column visible and adjusts the column span for the table.
+         *
+         * @since 3.0.0
+         * @param {string} column The column name.
+         *
+         * @returns {void}
+         */
         checked : function(column) {
                 $('.column-' + column).removeClass( 'hidden' );
                 this.colSpanChange(+1);
         },
 
+        /**
+         * @summary Hides a column and adjusts the column span for the table.
+         *
+         * @since 3.0.0
+         * @param {string} column The column name.
+         *
+         * @returns {void}
+         */
         unchecked : function(column) {
                 $('.column-' + column).addClass( 'hidden' );
                 this.colSpanChange(-1);
         },
 
+        /**
+         * @summary Get all hidden columns.
+         *
+         * @since 3.0.0
+         *
+         * @returns {string} The hidden column names separated by a comma.
+         */
         hidden : function() {
                 return $( '.manage-column[id]' ).filter( ':hidden' ).map(function() {
                         return this.id;
                 }).get().join( ',' );
         },
 
+        /**
+         * @summary Gets the checked column toggles from the screen options.
+         *
+         * @since 3.0.0
+         *
+         * @returns {string} String containing the checked column names.
+         */
         useCheckboxesForHidden : function() {
                 this.hidden = function(){
                         return $('.hide-column-tog').not(':checked').map(function() {
@@ -65 +124 @@
                 };
         },
 
+        /**
+         * @summary Adjusts the column span for the table.
+         *
+         * @since 3.1.0
+         *
+         * @param {int} diff The modifier for the column span.
+         */
         colSpanChange : function(diff) {
                 var $t = $('table').find('.colspanchange'), n;
                 if ( !$t.length )
@@ -75 +141 @@
 };
 
 $document.ready(function(){columns.init();});
-
+/**
+ * @summary Validates that the required form fields are not empty.
+ *
+ * @since 2.9.0
+ *
+ * @param {jQuery} form The form to validate.
+ *
+ * @returns {boolean} Returns true if all required fields are not an empty string.
+ */
 validateForm = function( form ) {
         return !$( form )
                 .find( '.form-required' )
@@ -87 +161 @@
 };
 
 // stub for doing better warnings
+/**
+ * @summary Shows message pop-up notice or confirmation message.
+ *
+ * @since 2.7.0
+ *
+ * @type {{warn: showNotice.warn, note: showNotice.note}}
+ *
+ * @returns {void}
+ */
 showNotice = {
+        /**
+         * @summary Shows a delete confirmation pop-up message.
+         *
+         * @since 2.7.0
+         *
+         * @returns {boolean} Returns true if the message is confirmed.
+         */
         warn : function() {
                 var msg = commonL10n.warnDelete || '';
                 if ( confirm(msg) ) {
@@ -97 +187 @@
                 return false;
         },
 
+        /**
+         * @summary Shows an alert message.
+         *
+         * @since 2.7.0
+         *
+         * @param text The text to display in the message.
+         */
         note : function(text) {
                 alert(text);
         }
 };
 
+/**
+ * @summary Represents the functions for the meta screen options panel.
+ *
+ * @since 3.2.0
+ *
+ * @type {{element: null, toggles: null, page: null, init: screenMeta.init,
+ *         toggleEvent: screenMeta.toggleEvent, open: screenMeta.open,
+ *         close: screenMeta.close}}
+ *
+ * @returns {void}
+ */
 screenMeta = {
         element: null, // #screen-meta
         toggles: null, // .screen-meta-toggle
         page:    null, // #wpcontent
 
+        /**
+         * @summary Initializes the screen meta options panel.
+         *
+         * @since 3.2.0
+         *
+         * @returns {void}
+         */
         init: function() {
                 this.element = $('#screen-meta');
                 this.toggles = $( '#screen-meta-links' ).find( '.show-settings' );
@@ -115 +230 @@
                 this.toggles.click( this.toggleEvent );
         },
 
+        /**
+         * @summary Toggles the screen meta options panel.
+         *
+         * @since 3.2.0
+         *
+         * @returns {void}
+         */
         toggleEvent: function() {
                 var panel = $( '#' + $( this ).attr( 'aria-controls' ) );
 
@@ -127 +249 @@
                         screenMeta.open( panel, $(this) );
         },
 
+        /**
+         * @summary Opens the screen meta options panel.
+         *
+         * @since 3.2.0
+         *
+         * @param {jQuery} panel  The screen meta options panel div.
+         * @param {jQuery} button The toggle button.
+         *
+         * @returns {void}
+         */
         open: function( panel, button ) {
 
                 $( '#screen-meta-links' ).find( '.screen-meta-toggle' ).not( button.parent() ).css( 'visibility', 'hidden' );
 
                 panel.parent().show();
+                /**
+                 * @summary Sets the focus to the meta options panel and adds the necessary CSS classes.
+                 *
+                 * @since 3.2.0
+                 *
+                 * @returns {void}
+                 */
                 panel.slideDown( 'fast', function() {
                         panel.focus();
                         button.addClass( 'screen-meta-active' ).attr( 'aria-expanded', true );
@@ -140 +279 @@
                 $document.trigger( 'screen:options:open' );
         },
 
+        /**
+         * @summary Closes the screen meta options panel.
+         *
+         * @since 3.2.0
+         *
+         * @param {jQuery} panel  The screen meta options panel div.
+         * @param {jQuery} button The toggle button.
+         *
+         * @returns {void}
+         */
         close: function( panel, button ) {
+                /**
+                 * @summary Hides the screen meta options panel.
+                 *
+                 * @since 3.2.0
+                 *
+                 * @returns {void}
+                 */
                 panel.slideUp( 'fast', function() {
                         button.removeClass( 'screen-meta-active' ).attr( 'aria-expanded', false );
                         $('.screen-meta-toggle').css('visibility', '');
@@ -152 +308 @@
 };
 
 /**
- * Help tabs.
+ * @summary Initializes the help tabs in the help panel.
+ *
+ * @param {Event} e The event object.
+ *
+ * @returns {void}
  */
 $('.contextual-help-tabs').delegate('a', 'click', function(e) {
         var link = $(this),
@@ -330 +490 @@
                 $headerEnd = $( '.wp-header-end' );
 
 
-        // when the menu is folded, make the fly-out submenu header clickable
+        /**
+         * @summary Makes the fly-out submenu header clickable, when the menu is folded.
+         *
+         * @param {Event} e The event object.
+         *
+         * @returns {void}
+         */
         $adminmenu.on('click.wp-submenu-head', '.wp-submenu-head', function(e){
                 $(e.target).parent().siblings('a').get(0).click();
         });
 
+        /**
+         * @summary Collapses the admin menu.
+         *
+         * @returns {void}
+         */
         $( '#collapse-button' ).on( 'click.collapse-menu', function() {
                 var viewportWidth = getViewportWidth() || 961;
 
@@ -367 +538 @@
                 $document.trigger( 'wp-collapse-menu', { state: menuState } );
         });
 
-        // Handle the `aria-haspopup` attribute on the current menu item when it has a sub-menu.
+        /**
+         * @summary Handles the `aria-haspopup` attribute on the current menu item when it has a submenu.
+         *
+         * @since 4.4.0
+         *
+         * @returns {void}
+         */
         function currentMenuItemHasPopup() {
                 var $current = $( 'a.wp-has-current-submenu' );
 
@@ -383 +560 @@
         $document.on( 'wp-menu-state-set wp-collapse-menu wp-responsive-activate wp-responsive-deactivate', currentMenuItemHasPopup );
 
         /**
-         * Ensure an admin submenu is within the visual viewport.
+         * @summary Ensures an admin submenu is within the visual viewport.
          *
          * @since 4.1.0
          *
          * @param {jQuery} $menuItem The parent menu item containing the submenu.
+         *
+         * @returns {void}
          */
         function adjustSubmenu( $menuItem ) {
                 var bottomOffset, pageHeight, adjustment, theFold, menutop, wintop, maxtop,
@@ -421 +600 @@
                 // iOS Safari works with touchstart, the rest work with click
                 mobileEvent = isIOS ? 'touchstart' : 'click';
 
-                // close any open submenus when touch/click is not on the menu
+                /**
+                 * @summary Closes any open submenus when touch/click is not on the menu.
+                 *
+                 * @param {Event} e The event object.
+                 *
+                 * @returns {void}
+                 */
                 $body.on( mobileEvent+'.wp-mobile-hover', function(e) {
                         if ( $adminmenu.data('wp-responsive') ) {
                                 return;
@@ -432 +617 @@
                         }
                 });
 
+                /**
+                 * @summary Handles the opening or closing the submenu based on the mobile click|touch event.
+                 *
+                 * @param {Event} event The event object.
+                 *
+                 * @returns {void}
+                 */
                 $adminmenu.find( 'a.wp-has-submenu' ).on( mobileEvent + '.wp-mobile-hover', function( event ) {
                         var $menuItem = $(this).parent();
 
@@ -453 +645 @@
 
         if ( ! isIOS && ! isAndroid ) {
                 $adminmenu.find( 'li.wp-has-submenu' ).hoverIntent({
+
+                        /**
+                         * @summary Opens the submenu when hovered over the menu item for desktops.
+                         *
+                         * @returns {void}
+                         */
                         over: function() {
                                 var $menuItem = $( this ),
                                         $submenu = $menuItem.find( '.wp-submenu' ),
@@ -471 +669 @@
                                 $adminmenu.find( 'li.opensub' ).removeClass( 'opensub' );
                                 $menuItem.addClass( 'opensub' );
                         },
+
+                        /**
+                         * @summary Closes the submenu when no longer hovering the menu item.
+                         *
+                         * @returns {void}
+                         */
                         out: function(){
                                 if ( $adminmenu.data( 'wp-responsive' ) ) {
                                         // The menu is in responsive mode, bail
@@ -484 +688 @@
                         interval: 90
                 });
 
+                /**
+                 * @summary Opens the submenu on when focused on the menu item.
+                 *
+                 * @param {Event} event The event object.
+                 *
+                 * @returns {void}
+                 */
                 $adminmenu.on( 'focus.adminmenu', '.wp-submenu a', function( event ) {
                         if ( $adminmenu.data( 'wp-responsive' ) ) {
                                 // The menu is in responsive mode, bail
@@ -491 +702 @@
                         }
 
                         $( event.target ).closest( 'li.menu-top' ).addClass( 'opensub' );
+
+                        /**
+                         * @summary Closes the submenu on blur from the menu item.
+                         *
+                         * @param {Event} event The event object.
+                         *
+                         * @returns {void}
+                         */
                 }).on( 'blur.adminmenu', '.wp-submenu a', function( event ) {
                         if ( $adminmenu.data( 'wp-responsive' ) ) {
                                 return;
                         }
 
                         $( event.target ).closest( 'li.menu-top' ).removeClass( 'opensub' );
+
+                        /**
+                         * @summary Adjusts the size for the submenu.
+                         *
+                         * @returns {void}
+                         */
                 }).find( 'li.wp-has-submenu.wp-not-current-submenu' ).on( 'focusin.adminmenu', function() {
                         adjustSubmenu( $( this ) );
                 });
@@ -513 +738 @@
         }
         $( 'div.updated, div.error, div.notice' ).not( '.inline, .below-h2' ).insertAfter( $headerEnd );
 
-        // Make notices dismissible
+        /**
+         * @summary Make notices dismissible.
+         *
+         * @since 4.4.0
+         *
+         * @returns {void}
+         */
         function makeNoticesDismissible() {
                 $( '.notice.is-dismissible' ).each( function() {
                         var $el = $( this ),
@@ -540 +771 @@
         // Init screen meta
         screenMeta.init();
 
-        // This event needs to be delegated. Ticket #37973.
+        /**
+         * @summary Checks a checkbox.
+         *
+         * This event needs to be delegated. Ticket #37973.
+         *
+         * @returns {boolean} Returns whether a checkbox is checked or not.
+         */
         $body.on( 'click', 'tbody > tr > .check-column :checkbox', function( event ) {
                 // Shift click to select a range of checkboxes.
                 if ( 'undefined' == event.shiftKey ) { return true; }
@@ -564 +801 @@
 
                 // Toggle the "Select all" checkboxes depending if the other ones are all checked or not.
                 var unchecked = $(this).closest('tbody').find(':checkbox').filter(':visible:enabled').not(':checked');
+
+                /**
+                 * @summary Determines if all checkboxes are checked.
+                 *
+                 * @returns {boolean} Returns true if there are no unchecked checkboxes.
+                 */
                 $(this).closest('table').children('thead, tfoot').find(':checkbox').prop('checked', function() {
                         return ( 0 === unchecked.length );
                 });
@@ -571 +814 @@
                 return true;
         });
 
-        // This event needs to be delegated. Ticket #37973.
+        /**
+         * @summary Controls all the toggles on bulk toggle change.
+         *
+         * When the bulk checkbox is changed, all the checkboxes in the tables are changed accordingly.
+         * When the shift-button is pressed while changing the bulk checkbox the checkboxes in the table are inverted.
+         *
+         * This event needs to be delegated. Ticket #37973.
+         *
+         * @param {Event} event The event object.
+         *
+         * @returns {boolean}
+         */
         $body.on( 'click.wp-toggle-checkboxes', 'thead .check-column :checkbox, tfoot .check-column :checkbox', function( event ) {
                 var $this = $(this),
                         $table = $this.closest( 'table' ),
@@ -580 +834 @@
 
                 $table.children( 'tbody' ).filter(':visible')
                         .children().children('.check-column').find(':checkbox')
+                        /**
+                         * @summary Updates the checked state on the checkbox in the table.
+                         *
+                         * @returns {boolean} True checks the checkbox, False unchecks the checkbox.
+                         */
                         .prop('checked', function() {
                                 if ( $(this).is(':hidden,:disabled') ) {
                                         return false;
@@ -596 +855 @@
 
                 $table.children('thead,  tfoot').filter(':visible')
                         .children().children('.check-column').find(':checkbox')
+                        /**
+                         * @summary Syncs the bulk checkboxes on the top and bottom of the table.
+                         *
+                         * @returns {boolean} True checks the checkbox, False unchecks the checkbox.
+                         */
                         .prop('checked', function() {
                                 if ( toggle ) {
                                         return false;
@@ -607 +871 @@
                         });
         });
 
-        // Show row actions on keyboard focus of its parent container element or any other elements contained within
+        /**
+         * @summary Shows row actions on focus of its parent container element or any other elements contained within.
+         *
+         * @returns {void}
+         */
         $( '#wpbody-content' ).on({
                 focusin: function() {
                         clearTimeout( transitionTimeout );
@@ -636 +904 @@
                 return false;
         });
 
-        // tab in textareas
+        /**
+         * @summary Handles tab keypresses in theme and plugin editor textareas.
+         *
+         * @param {Event} e The event object.
+         *
+         * @returns {void}
+         */
         $('#newcontent').bind('keydown.wpevent_InsertTab', function(e) {
                 var el = e.target, selStart, selEnd, val, scroll, sel;
 
-                if ( e.keyCode == 27 ) { // escape key
+                // After pressing escape key (keyCode: 27), the tab key should tab out of the textarea.
+                if ( e.keyCode == 27 ) {
                         // when pressing Escape: Opera 12 and 27 blur form fields, IE 8 clears them
                         e.preventDefault();
                         $(el).data('tab-out', true);
                         return;
                 }
 
-                if ( e.keyCode != 9 || e.ctrlKey || e.altKey || e.shiftKey ) // tab key
+                // Only listen for plain tab key (keyCode: 9) without any modifiers.
+                if ( e.keyCode != 9 || e.ctrlKey || e.altKey || e.shiftKey )
                         return;
 
+                // After tabbing out, reset it so next time the tab key can be used again.
                 if ( $(el).data('tab-out') ) {
                         $(el).data('tab-out', false);
                         return;
@@ -659 +936 @@
                 selEnd = el.selectionEnd;
                 val = el.value;
 
+                // If any text is selected, replace the selection with a tab character.
                 if ( document.selection ) {
                         el.focus();
                         sel = document.selection.createRange();
@@ -670 +948 @@
                         this.scrollTop = scroll;
                 }
 
+                // Cancel the regular tab functionality, to prevent losing focus of the textarea.
                 if ( e.stopPropagation )
                         e.stopPropagation();
                 if ( e.preventDefault )
                         e.preventDefault();
         });
 
+        // Reset page number variable for new filters/searches but not for bulk actions. See #17685.
         if ( pageInput.length ) {
+                /**
+                 * @summary Handles pagination variable when filtering the list table.
+                 *
+                 * Set the pagination argument to the first page when the post-filter form is submitted.
+                 * This happens when pressing the 'filter' button on the list table page.
+                 *
+                 * The pagination argument should not be touched when the bulk action dropdowns are set to do anything.
+                 *
+                 * The form closest to the pageInput is the post-filter form.
+                 *
+                 * @returns {void}
+                 */
                 pageInput.closest('form').submit( function() {
-
-                        // Reset paging var for new filters/searches but not for bulk actions. See #17685.
+                        /*
+                         * action = bulk action dropdown at the top of the table
+                         * action2 = bulk action dropdow at the bottom of the table
+                         */
                         if ( $('select[name="action"]').val() == -1 && $('select[name="action2"]').val() == -1 && pageInput.val() == currentPage )
                                 pageInput.val('1');
                 });
         }
 
+        /**
+         * @summary Resets the bulk actions when the search button is clicked.
+         *
+         * @returns {void}
+         */
         $('.search-box input[type="search"], .search-box input[type="submit"]').mousedown(function () {
                 $('select[name^="action"]').val('-1');
         });
 
-        // Scroll into view when focused
+        /**
+         * @summary Scrolls into view when focus.scroll-into-view is triggered.
+         *
+         * @param {Event} e The event object.
+         *
+         * @returns {void}
+         */
         $('#contextual-help-link, #show-settings-link').on( 'focus.scroll-into-view', function(e){
                 if ( e.target.scrollIntoView )
                         e.target.scrollIntoView(false);
         });
 
-        // Disable upload buttons until files are selected
+        /**
+         * @summary Disables the submit upload buttons when no data is entered.
+         *
+         * @returns {void}
+         */
         (function(){
                 var button, input, form = $('form.wp-upload-form');
+
+                // Exit when no upload form is found.
                 if ( ! form.length )
                         return;
+
                 button = form.find('input[type="submit"]');
                 input = form.find('input[type="file"]');
 
+                /**
+                 * @summary Determines if any data is entered in any file upload input.
+                 *
+                 * @since 3.5.0
+                 *
+                 * @returns {void}
+                 */
                 function toggleUploadButton() {
+                        // When no inputs have a value, disable the upload buttons.
                         button.prop('disabled', '' === input.map( function() {
                                 return $(this).val();
                         }).get().join(''));
                 }
+
+                // Update the status initially.
                 toggleUploadButton();
+                // Update the status when any file input changes.
                 input.on('change', toggleUploadButton);
         })();
 
+        /**
+         * @summary Pins the menu while distraction-free writing is enabled.
+         *
+         * @param {Event} event Event data.
+         *
+         * @since 4.1.0
+         *
+         * @returns {void}
+         */
         function pinMenu( event ) {
                 var windowPos = $window.scrollTop(),
                         resizing = ! event || event.type !== 'scroll';
@@ -720 +1052 @@
                         return;
                 }
 
+                /*
+                 * When the menu is higher than the window and smaller than the entire page.
+                 * It should be adjusted to be able to see the entire menu.
+                 *
+                 * Otherwise it can be accessed normally.
+                 */
                 if ( height.menu + height.adminbar < height.window ||
                         height.menu + height.adminbar + 20 > height.wpwrap ) {
                         unpinMenu();
@@ -728 +1066 @@
 
                 menuIsPinned = true;
 
+                // If the menu is higher than the window, compensate on scroll.
                 if ( height.menu + height.adminbar > height.window ) {
-                        // Check for overscrolling
+                        // Check for overscrolling, this happens when swiping up at the top of the document in modern browsers.
                         if ( windowPos < 0 ) {
+                                // Stick the menu to the top.
                                 if ( ! pinnedMenuTop ) {
                                         pinnedMenuTop = true;
                                         pinnedMenuBottom = false;
@@ -744 +1084 @@
 
                                 return;
                         } else if ( windowPos + height.window > $document.height() - 1 ) {
+                                // When overscrolling at the bottom, stick the menu to the bottom.
                                 if ( ! pinnedMenuBottom ) {
                                         pinnedMenuBottom = true;
                                         pinnedMenuTop = false;
@@ -759 +1100 @@
                         }
 
                         if ( windowPos > lastScrollPosition ) {
-                                // Scrolling down
+                                // When a down scroll has been detected.
+
+                                // If it was pinned to the top, unpin and calculate relative scroll.
                                 if ( pinnedMenuTop ) {
-                                        // let it scroll
                                         pinnedMenuTop = false;
+                                        // Calculate new offset position.
                                         menuTop = $adminMenuWrap.offset().top - height.adminbar - ( windowPos - lastScrollPosition );
 
                                         if ( menuTop + height.menu + height.adminbar < windowPos + height.window ) {
@@ -775 +1118 @@
                                                 bottom: ''
                                         });
                                 } else if ( ! pinnedMenuBottom && $adminMenuWrap.offset().top + height.menu < windowPos + height.window ) {
-                                        // pin the bottom
+                                        // Pin it to the bottom.
                                         pinnedMenuBottom = true;
 
                                         $adminMenuWrap.css({
@@ -785 +1128 @@
                                         });
                                 }
                         } else if ( windowPos < lastScrollPosition ) {
-                                // Scrolling up
+                                // When a scroll up is detected.
+
+                                // If it was pinned to the bottom, unpin and calculate relative scroll.
                                 if ( pinnedMenuBottom ) {
-                                        // let it scroll
                                         pinnedMenuBottom = false;
+                                        // Calculate new offset position.
                                         menuTop = $adminMenuWrap.offset().top - height.adminbar + ( lastScrollPosition - windowPos );
 
                                         if ( menuTop + height.menu > windowPos + height.window ) {
@@ -801 +1146 @@
                                                 bottom: ''
                                         });
                                 } else if ( ! pinnedMenuTop && $adminMenuWrap.offset().top >= windowPos + height.adminbar ) {
-                                        // pin the top
+                                        // Pin it to the top.
                                         pinnedMenuTop = true;
 
                                         $adminMenuWrap.css({
@@ -811 +1156 @@
                                         });
                                 }
                         } else if ( resizing ) {
-                                // Resizing
+                                // Window is being resized.
+
                                 pinnedMenuTop = pinnedMenuBottom = false;
+
+                                // Calculate the new offset.
                                 menuTop = windowPos + height.window - height.menu - height.adminbar - 1;
 
                                 if ( menuTop > 0 ) {
@@ -830 +1178 @@
                 lastScrollPosition = windowPos;
         }
 
+        /**
+         * @summary Determines the height of certain elements.
+         *
+         * @since 4.1.0
+         *
+         * @returns {void}
+         */
         function resetHeights() {
                 height = {
                         window: $window.height(),
@@ -839 +1194 @@
                 };
         }
 
+        /**
+         * @summary Unpins the menu.
+         *
+         * @since 4.1.0
+         *
+         * @returns {void}
+         */
         function unpinMenu() {
                 if ( isIOS || ! menuIsPinned ) {
                         return;
@@ -852 +1214 @@
                 });
         }
 
+        /**
+         * @summary Pins and unpins the menu when applicable.
+         *
+         * @since 4.1.0
+         *
+         * @returns {void}
+         */
         function setPinMenu() {
                 resetHeights();
 
@@ -874 +1243 @@
                 });
         }
 
+        /**
+         * @summary Changes properties of metaboxes and body.
+         *
+         * Changes the sortables and responsiveness of metaboxes.
+         *
+         * @since 3.8.0
+         *
+         *@returns {void}
+         */
         window.wpResponsive = {
+
+                /**
+                 * @summary Initializes the wpResponsive object.
+                 *
+                 * @since 3.8.0
+                 *
+                 * @returns {void}
+                 */
                 init: function() {
                         var self = this;
 
@@ -887 +1273 @@
 
                         $( '#wp-admin-bar-menu-toggle a' ).attr( 'aria-expanded', 'false' );
 
-                        // Toggle sidebar when toggle is clicked
+                        // Toggle sidebar when toggle is clicked.
                         $( '#wp-admin-bar-menu-toggle' ).on( 'click.wp-responsive', function( event ) {
                                 event.preventDefault();
 
-                                // close any open toolbar submenus
+                                // close any open toolbar submenus.
                                 $adminbar.find( '.hover' ).removeClass( 'hover' );
 
                                 $wpwrap.toggleClass( 'wp-responsive-open' );
@@ -903 +1289 @@
                                 }
                         } );
 
-                        // Add menu events
+                        // Add menu events.
                         $adminmenu.on( 'click.wp-responsive', 'li.wp-has-submenu > a', function( event ) {
                                 if ( ! $adminmenu.data('wp-responsive') ) {
                                         return;
@@ -916 +1302 @@
                         self.trigger();
                         $document.on( 'wp-window-resized.wp-responsive', $.proxy( this.trigger, this ) );
 
-                        // This needs to run later as UI Sortable may be initialized later on $(document).ready()
+                        // This needs to run later as UI Sortable may be initialized later on $(document).ready().
                         $window.on( 'load.wp-responsive', function() {
                                 var width = navigator.userAgent.indexOf('AppleWebKit/') > -1 ? $window.width() : window.innerWidth;
 
@@ -926 +1312 @@
                         });
                 },
 
+                /**
+                 * @summary Changes properties of body and admin menu.
+                 *
+                 * Pins and unpins the menu and adds the auto-fold class to the body.
+                 * Makes the admin menu responsive and disables the metabox sortables.
+                 *
+                 * @since 3.8.0
+                 *
+                 * @returns {void}
+                 */
                 activate: function() {
                         setPinMenu();
 
-                        if ( ! $body.hasClass( 'auto-fold' ) ) {
-                                $body.addClass( 'auto-fold' );
+                        if ( ! $body.hasClass( "auto-fold" ) ) {
+                                $body.addClass( "auto-fold" );
                         }
 
-                        $adminmenu.data( 'wp-responsive', 1 );
+                        $adminmenu.data( "wp-responsive", 1 );
                         this.disableSortables();
                 },
 
+                /**
+                 * @summary Changes properties of admin menu and enables metabox sortables.
+                 *
+                 * Pin and unpin the menu.
+                 * Removes the responsiveness of the admin menu and enables the metabox sortables.
+                 *
+                 * @since 3.8.0
+                 *
+                 * @returns {void}
+                 */
                 deactivate: function() {
                         setPinMenu();
                         $adminmenu.removeData('wp-responsive');
                         this.enableSortables();
                 },
 
+                /**
+                 * @summary Sets the responsiveness and enables the overlay based on the viewport width.
+                 *
+                 * @since 3.8.0
+                 *
+                 * @returns {void}
+                 */
                 trigger: function() {
                         var viewportWidth = getViewportWidth();
 
@@ -953 +1366 @@
 
                         if ( viewportWidth <= 782 ) {
                                 if ( ! wpResponsiveActive ) {
-                                        $document.trigger( 'wp-responsive-activate' );
+                                        $document.trigger( "wp-responsive-activate" );
                                         wpResponsiveActive = true;
                                 }
                         } else {
                                 if ( wpResponsiveActive ) {
-                                        $document.trigger( 'wp-responsive-deactivate' );
+                                        $document.trigger( "wp-responsive-deactivate" );
                                         wpResponsiveActive = false;
                                 }
                         }
@@ -970 +1383 @@
                         }
                 },
 
+                /**
+                 * @summary Inserts a responsive overlay and toggles the window.
+                 *
+                 * @since 3.8.0
+                 *
+                 * @returns {void}
+                 */
                 enableOverlay: function() {
                         if ( $overlay.length === 0 ) {
                                 $overlay = $( '<div id="wp-responsive-overlay"></div>' )
@@ -986 +1406 @@
                         });
                 },
 
+                /**
+                 * @summary Disables the responsive overlay and removes the overlay.
+                 *
+                 * @since 3.8.0
+                 *
+                 * @returns {void}
+                 */
                 disableOverlay: function() {
-                        $toolbarPopups.off( 'click.wp-responsive' );
+                        $toolbarPopups.off( "click.wp-responsive" );
                         $overlay.hide();
                 },
 
+                /**
+                 * @summary Disables sortables.
+                 *
+                 * @since 3.8.0
+                 *
+                 * @returns {void}
+                 */
                 disableSortables: function() {
                         if ( $sortables.length ) {
                                 try {
-                                        $sortables.sortable('disable');
-                                } catch(e) {}
+                                        $sortables.sortable( "disable" );
+                                } catch ( e ) {}
                         }
                 },
 
+                /**
+                 * @summary Enables sortables.
+                 *
+                 * @since 3.8.0
+                 *
+                 * @returns {void}
+                 */
                 enableSortables: function() {
                         if ( $sortables.length ) {
                                 try {
-                                        $sortables.sortable('enable');
-                                } catch(e) {}
+                                        $sortables.sortable( "enable" );
+                                } catch ( e ) {}
                         }
                 }
         };
 
-        // Add an ARIA role `button` to elements that behave like UI controls when JavaScript is on.
+        /**
+         * @summary Add an ARIA role `button` to elements that behave like UI controls when JavaScript is on.
+         *
+         * @since 4.5.0
+         *
+         * @returns {void}
+         */
         function aria_button_if_js() {
-                $( '.aria-button-if-js' ).attr( 'role', 'button' );
+                $( ".aria-button-if-js" ).attr( "role", "button" );
         }
 
         $( document ).ajaxComplete( function() {
@@ -1037 +1484 @@
         }
 
         /**
-         * @summary Set the admin menu collapsed/expanded state.
+         * @summary Sets the admin menu collapsed/expanded state.
          *
          * Sets the global variable `menuState` and triggers a custom event passing
          * the current menu state.
@@ -1064 +1511 @@
         $document.on( 'wp-window-resized.set-menu-state', setMenuState );
 
         /**
-         * @summary Set ARIA attributes on the collapse/expand menu button.
+         * @summary Sets ARIA attributes on the collapse/expand menu button.
          *
          * When the admin menu is open or folded, updates the `aria-expanded` and
          * `aria-label` attributes of the button to give feedback to assistive
@@ -1122 +1569 @@
         });
 });
 
-// Fire a custom jQuery event at the end of window resize
+// Fire a custom jQuery event at the end of window resize.
 ( function() {
         var timeout;
 
+        /**
+         * @summary Triggers the WP window-resize event.
+         *
+         * @since 3.8.0
+         *
+         * @returns {void}
+         */
+
         function triggerEvent() {
-                $document.trigger( 'wp-window-resized' );
+                $document.trigger( "wp-window-resized" );
         }
 
+        /**
+         * @summary Fires the trigger event again after 200 ms.
+         *
+         * @since 3.8.0
+         *
+         * @returns {void}
+         */
         function fireOnce() {
                 window.clearTimeout( timeout );
                 timeout = window.setTimeout( triggerEvent, 200 );