diff -r c7c34916027a -r 177826044cd9 wp/wp-admin/js/common.js
--- a/wp/wp-admin/js/common.js	Mon Oct 14 18:06:33 2019 +0200
+++ b/wp/wp-admin/js/common.js	Mon Oct 14 18:28:13 2019 +0200
@@ -1,13 +1,29 @@
+/**
+ * @output wp-admin/js/common.js
+ */
+
 /* global setUserSetting, ajaxurl, commonL10n, alert, confirm, pagenow */
-var showNotice, adminMenu, columns, validateForm, screenMeta;
+/* global columns, screenMeta */
+
+/**
+ *  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
-adminMenu = {
+/**
+ * Removed in 3.3.0, needed for back-compatibility.
+ *
+ * @since 2.7.0
+ * @deprecated 3.3.0
+ */
+window.adminMenu = {
 	init : function() {},
 	fold : function() {},
 	restoreMenuState : function() {},
@@ -15,8 +31,19 @@
 	favorites : function() {}
 };
 
-// show/hide/save table columns
-columns = {
+// Show/hide/save table columns.
+window.columns = {
+
+	/**
+	 * 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() {
@@ -30,6 +57,15 @@
 		});
 	},
 
+	/**
+	 * 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,22 +76,52 @@
 		});
 	},
 
+	/**
+	 * 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);
 	},
 
+	/**
+	 * 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);
 	},
 
+	/**
+	 * Gets 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 $( '.manage-column[id]' ).filter( '.hidden' ).map(function() {
 			return this.id;
 		}).get().join( ',' );
 	},
 
+	/**
+	 * 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,6 +131,13 @@
 		};
 	},
 
+	/**
+	 * 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 )
@@ -76,7 +149,16 @@
 
 $document.ready(function(){columns.init();});
 
-validateForm = function( form ) {
+/**
+ * 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.
+ */
+window.validateForm = function( form ) {
 	return !$( form )
 		.find( '.form-required' )
 		.filter( function() { return $( ':input:visible', this ).val() === ''; } )
@@ -87,7 +169,24 @@
 };
 
 // stub for doing better warnings
-showNotice = {
+/**
+ * Shows message pop-up notice or confirmation message.
+ *
+ * @since 2.7.0
+ *
+ * @type {{warn: showNotice.warn, note: showNotice.note}}
+ *
+ * @returns {void}
+ */
+window.showNotice = {
+
+	/**
+	 * 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,16 +196,41 @@
 		return false;
 	},
 
+	/**
+	 * Shows an alert message.
+	 *
+	 * @since 2.7.0
+	 *
+	 * @param text The text to display in the message.
+	 */
 	note : function(text) {
 		alert(text);
 	}
 };
 
-screenMeta = {
+/**
+ * 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}
+ */
+window.screenMeta = {
 	element: null, // #screen-meta
 	toggles: null, // .screen-meta-toggle
 	page:    null, // #wpcontent
 
+	/**
+	 * 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,6 +239,13 @@
 		this.toggles.click( this.toggleEvent );
 	},
 
+	/**
+	 * Toggles the screen meta options panel.
+	 *
+	 * @since 3.2.0
+	 *
+	 * @returns {void}
+	 */
 	toggleEvent: function() {
 		var panel = $( '#' + $( this ).attr( 'aria-controls' ) );
 
@@ -127,11 +258,29 @@
 			screenMeta.open( panel, $(this) );
 	},
 
+	/**
+	 * 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();
+
+		/**
+		 * 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,7 +289,24 @@
 		$document.trigger( 'screen:options:open' );
 	},
 
+	/**
+	 * 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 ) {
+		/**
+		 * 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,7 +318,11 @@
 };
 
 /**
- * Help tabs.
+ * 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),
@@ -178,7 +348,6 @@
 /**
  * Update custom permalink structure via buttons.
  */
-
 var permalinkStructureFocused = false,
     $permalinkStructure       = $( '#permalink_structure' ),
     $permalinkStructureInputs = $( '.permalink-structure input:radio' ),
@@ -329,12 +498,22 @@
 		},
 		$headerEnd = $( '.wp-header-end' );
 
-
-	// when the menu is folded, make the fly-out submenu header clickable
+	/**
+	 * 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();
 	});
 
+	/**
+	 * Collapses the admin menu.
+	 *
+	 * @returns {void}
+	 */
 	$( '#collapse-button' ).on( 'click.collapse-menu', function() {
 		var viewportWidth = getViewportWidth() || 961;
 
@@ -367,7 +546,13 @@
 		$document.trigger( 'wp-collapse-menu', { state: menuState } );
 	});
 
-	// Handle the `aria-haspopup` attribute on the current menu item when it has a sub-menu.
+	/**
+	 * 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,11 +568,13 @@
 	$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.
+	 * 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,7 +608,13 @@
 		// 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
+		/**
+		 * 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,6 +625,13 @@
 			}
 		});
 
+		/**
+		 * 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,6 +653,12 @@
 
 	if ( ! isIOS && ! isAndroid ) {
 		$adminmenu.find( 'li.wp-has-submenu' ).hoverIntent({
+
+			/**
+			 * Opens the submenu when hovered over the menu item for desktops.
+			 *
+			 * @returns {void}
+			 */
 			over: function() {
 				var $menuItem = $( this ),
 					$submenu = $menuItem.find( '.wp-submenu' ),
@@ -471,6 +677,12 @@
 				$adminmenu.find( 'li.opensub' ).removeClass( 'opensub' );
 				$menuItem.addClass( 'opensub' );
 			},
+
+			/**
+			 * 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,6 +696,13 @@
 			interval: 90
 		});
 
+		/**
+		 * 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,12 +710,26 @@
 			}
 
 			$( event.target ).closest( 'li.menu-top' ).addClass( 'opensub' );
+
+			/**
+			 * 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' );
+
+			/**
+			 * Adjusts the size for the submenu.
+			 *
+			 * @returns {void}
+			 */
 		}).find( 'li.wp-has-submenu.wp-not-current-submenu' ).on( 'focusin.adminmenu', function() {
 			adjustSubmenu( $( this ) );
 		});
@@ -513,7 +746,13 @@
 	}
 	$( 'div.updated, div.error, div.notice' ).not( '.inline, .below-h2' ).insertAfter( $headerEnd );
 
-	// Make notices dismissible
+	/**
+	 * Makes notices dismissible.
+	 *
+	 * @since 4.4.0
+	 *
+	 * @returns {void}
+	 */
 	function makeNoticesDismissible() {
 		$( '.notice.is-dismissible' ).each( function() {
 			var $el = $( this ),
@@ -540,7 +779,13 @@
 	// Init screen meta
 	screenMeta.init();
 
-	// This event needs to be delegated. Ticket #37973.
+	/**
+	 * 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,6 +809,12 @@
 
 		// 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');
+
+		/**
+		 * 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,7 +822,18 @@
 		return true;
 	});
 
-	// This event needs to be delegated. Ticket #37973.
+	/**
+	 * 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,6 +842,11 @@
 
 		$table.children( 'tbody' ).filter(':visible')
 			.children().children('.check-column').find(':checkbox')
+			/**
+			 * 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,6 +863,12 @@
 
 		$table.children('thead,  tfoot').filter(':visible')
 			.children().children('.check-column').find(':checkbox')
+
+			/**
+			 * 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,7 +880,11 @@
 			});
 	});
 
-	// Show row actions on keyboard focus of its parent container element or any other elements contained within
+	/**
+	 * 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,20 +913,29 @@
 		return false;
 	});
 
-	// tab in textareas
+	/**
+	 * 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,6 +945,7 @@
 		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,48 +957,103 @@
 			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 ) {
+
+		/**
+		 * 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');
 		});
 	}
 
+	/**
+	 * 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
+	/**
+	 * 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
+	/**
+	 * 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"]');
 
+		/**
+		 * 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);
 	})();
 
+	/**
+	 * 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,6 +1062,12 @@
 			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,9 +1076,11 @@
 
 		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,6 +1094,7 @@
 
 				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,10 +1110,12 @@
 			}
 
 			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,7 +1128,7 @@
 						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,10 +1138,13 @@
 					});
 				}
 			} 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,7 +1157,8 @@
 						bottom: ''
 					});
 				} else if ( ! pinnedMenuTop && $adminMenuWrap.offset().top >= windowPos + height.adminbar ) {
-					// pin the top
+
+					// Pin it to the top.
 					pinnedMenuTop = true;
 
 					$adminMenuWrap.css({
@@ -811,8 +1168,11 @@
 					});
 				}
 			} 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,6 +1190,13 @@
 		lastScrollPosition = windowPos;
 	}
 
+	/**
+	 * Determines the height of certain elements.
+	 *
+	 * @since 4.1.0
+	 *
+	 * @returns {void}
+	 */
 	function resetHeights() {
 		height = {
 			window: $window.height(),
@@ -839,6 +1206,13 @@
 		};
 	}
 
+	/**
+	 * Unpins the menu.
+	 *
+	 * @since 4.1.0
+	 *
+	 * @returns {void}
+	 */
 	function unpinMenu() {
 		if ( isIOS || ! menuIsPinned ) {
 			return;
@@ -852,6 +1226,13 @@
 		});
 	}
 
+	/**
+	 * Pins and unpins the menu when applicable.
+	 *
+	 * @since 4.1.0
+	 *
+	 * @returns {void}
+	 */
 	function setPinMenu() {
 		resetHeights();
 
@@ -874,7 +1255,22 @@
 		});
 	}
 
+	/**
+	 * Changes the sortables and responsiveness of metaboxes.
+	 *
+	 * @since 3.8.0
+	 *
+	 *@returns {void}
+	 */
 	window.wpResponsive = {
+
+		/**
+		 * Initializes the wpResponsive object.
+		 *
+		 * @since 3.8.0
+		 *
+		 * @returns {void}
+		 */
 		init: function() {
 			var self = this;
 
@@ -887,11 +1283,11 @@
 
 			$( '#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,7 +1299,7 @@
 				}
 			} );
 
-			// 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,7 +1312,7 @@
 			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,6 +1322,16 @@
 			});
 		},
 
+		/**
+		 * 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();
 
@@ -937,12 +1343,29 @@
 			this.disableSortables();
 		},
 
+		/**
+		 * 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();
 		},
 
+		/**
+		 * Sets the responsiveness and enables the overlay based on the viewport width.
+		 *
+		 * @since 3.8.0
+		 *
+		 * @returns {void}
+		 */
 		trigger: function() {
 			var viewportWidth = getViewportWidth();
 
@@ -970,6 +1393,13 @@
 			}
 		},
 
+		/**
+		 * 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,29 +1416,56 @@
 			});
 		},
 
+		/**
+		 * Disables the responsive overlay and removes the overlay.
+		 *
+		 * @since 3.8.0
+		 *
+		 * @returns {void}
+		 */
 		disableOverlay: function() {
 			$toolbarPopups.off( 'click.wp-responsive' );
 			$overlay.hide();
 		},
 
+		/**
+		 * Disables sortables.
+		 *
+		 * @since 3.8.0
+		 *
+		 * @returns {void}
+		 */
 		disableSortables: function() {
 			if ( $sortables.length ) {
 				try {
-					$sortables.sortable('disable');
-				} catch(e) {}
+					$sortables.sortable( 'disable' );
+				} catch ( e ) {}
 			}
 		},
 
+		/**
+		 * 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.
+	/**
+	 * 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' );
 	}
@@ -1018,7 +1475,7 @@
 	});
 
 	/**
-	 * @summary Get the viewport width.
+	 * Get the viewport width.
 	 *
 	 * @since 4.7.0
 	 *
@@ -1037,7 +1494,7 @@
 	}
 
 	/**
-	 * @summary Set the admin menu collapsed/expanded state.
+	 * Sets the admin menu collapsed/expanded state.
 	 *
 	 * Sets the global variable `menuState` and triggers a custom event passing
 	 * the current menu state.
@@ -1064,7 +1521,7 @@
 	$document.on( 'wp-window-resized.set-menu-state', setMenuState );
 
 	/**
-	 * @summary Set ARIA attributes on the collapse/expand menu button.
+	 * 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,14 +1579,28 @@
 	});
 });
 
-// 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;
 
+	/**
+	 * Triggers the WP window-resize event.
+	 *
+	 * @since 3.8.0
+	 *
+	 * @returns {void}
+	 */
 	function triggerEvent() {
 		$document.trigger( 'wp-window-resized' );
 	}
 
+	/**
+	 * Fires the trigger event again after 200 ms.
+	 *
+	 * @since 3.8.0
+	 *
+	 * @returns {void}
+	 */
 	function fireOnce() {
 		window.clearTimeout( timeout );
 		timeout = window.setTimeout( triggerEvent, 200 );