enmi-conf.org: comparison wp/wp-admin/js/common.js

Mercurial Mercurial > enmi-conf.org / comparison

summary | shortlog | changelog | graph | tags | bookmarks | branches | files | changeset | file | latest | revisions | annotate | diff | comparison | raw | help

wp/wp-admin/js/common.js

changeset 9	177826044cd9
parent 7	cf61fcea0001
child 16	a86126ab1dd4

equal deleted inserted replaced

-:c7c34916027a
+:177826044cd9
+/**
+* @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
+* Removed in 3.3.0, needed for back-compatibility.
-adminMenu = {
+*
+* @since 2.7.0
+* @deprecated 3.3.0
+*/
+window.adminMenu = {
 	init : function() {},
 	fold : function() {},
 	restoreMenuState : function() {},
 	toggle : function() {},
 	favorites : function() {}
 };
-// show/hide/save table columns
+// Show/hide/save table columns.
-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() {
 			var $t = $(this), column = $t.val();
 			if ( $t.prop('checked') )
 			columns.saveManageColumnsState();
 		});
 	},
+	/**
+	 * 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, {
 			action: 'hidden-columns',
 			hidden: hidden,
 			screenoptionnonce: $('#screenoptionnonce').val(),
 			page: pagenow
 		});
 	},
+	/**
+	 * 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() {
 				var id = this.id;
 				return id.substring( id, id.length - 5 );
 			}).get().join(',');
 		};
 	},
+	/**
+	 * 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 )
 			return;
 		n = parseInt( $t.attr('colspan'), 10 ) + diff;
 	}
 };
 $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() === ''; } )
 		.addClass( 'form-invalid' )
 		.find( ':input:visible' )
 		.change( function() { $( this ).closest( '.form-invalid' ).removeClass( 'form-invalid' ); } )
 		.length;
 };
 // 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) ) {
 			return true;
 		}
 		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' );
 		this.page    = $('#wpcontent');
 		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' ) );
 		if ( !panel.length )
 			return;
 			screenMeta.close( panel, $(this) );
 		else
 			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 );
 		});
 		$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', '');
 			panel.parent().hide();
 		});
 		$document.trigger( 'screen:options:close' );
 	}
 };
 /**
-* 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),
 		panel;
 });
 /**
 * Update custom permalink structure via buttons.
 */
 var permalinkStructureFocused = false,
 $permalinkStructure       = $( '#permalink_structure' ),
 $permalinkStructureInputs = $( '.permalink-structure input:radio' ),
 $permalinkCustomSelection = $( '#custom_selection' ),
 $availableStructureTags   = $( '.form-table.permalink-structure .available-structure-tags button' );
 			adminbar: $adminbar.height(),
 			menu: $adminMenuWrap.height()
 		},
 		$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;
 		// reset any compensation for submenus near the bottom of the screen
 		$('#adminmenu div.wp-submenu').css('margin-top', '');
 		}
 		$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' );
 		if ( 'folded' === menuState ) {
 			// When folded or auto-folded and not responsive view, the current menu item does have a fly-out sub-menu.
 	}
 	$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,
 			$submenu = $menuItem.find( '.wp-submenu' );
 	if ( 'ontouchstart' in window || /IEMobile\/[1-9]/.test(navigator.userAgent) ) { // touch screen device
 		// 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;
 			}
 			if ( ! $( e.target ).closest( '#adminmenu' ).length ) {
 				$adminmenu.find( 'li.opensub' ).removeClass( 'opensub' );
 			}
 		});
+		/**
+		 * 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();
 			if ( $adminmenu.data( 'wp-responsive' ) ) {
 				return;
 		});
 	}
 	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' ),
 					top = parseInt( $submenu.css( 'top' ), 10 );
 				adjustSubmenu( $menuItem );
 				$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
 					return;
 				}
 			timeout: 200,
 			sensitivity: 7,
 			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
 				return;
 			}
 			$( 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 ) );
 		});
 	}
 	if ( ! $headerEnd.length ) {
 		$headerEnd = $( '.wrap h1, .wrap h2' ).first();
 	}
 	$( '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 ),
 				$button = $( '<button type="button" class="notice-dismiss"><span class="screen-reader-text"></span></button>' ),
 				btnText = commonL10n.dismiss || '';
 	$document.on( 'wp-updates-notice-added wp-plugin-install-error wp-plugin-update-error wp-plugin-delete-error wp-theme-install-error wp-theme-delete-error', makeNoticesDismissible );
 	// 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; }
 		if ( event.shiftKey ) {
 			if ( !lastClicked ) { return true; }
 		}
 		lastClicked = this;
 		// 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 );
 		});
 		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' ),
 			controlChecked = $this.prop('checked'),
 			toggle = event.shiftKey || $this.data('wp-toggle');
 		$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;
 				}
 				return false;
 			});
 		$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;
 				} else if ( controlChecked ) {
 					return true;
 				return false;
 			});
 	});
-	// 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 );
 			focusedRowActions = $( this ).find( '.row-actions' );
 			// transitionTimeout is necessary for Firefox, but Chrome won't remove the CSS class without a little help.
 		setUserSetting('default_password_nag', 'hide');
 		$('div.default-password-nag').hide();
 		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;
 		}
 		selStart = el.selectionStart;
 		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();
 			sel.text = '\t';
 		} else if ( selStart >= 0 ) {
 			el.value = val.substring(0, selStart).concat('\t', val.substring(selEnd) );
 			el.selectionStart = el.selectionEnd = selStart + 1;
 			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';
 		if ( isIOS || isIE8 || $adminmenu.data( 'wp-responsive' ) ) {
 			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();
 			return;
 		}
 		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;
 					$adminMenuWrap.css({
 					});
 				}
 				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;
 					$adminMenuWrap.css({
 				return;
 			}
 			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 ) {
 						menuTop = windowPos + height.window - height.menu - height.adminbar;
 					}
 						position: 'absolute',
 						top: menuTop,
 						bottom: ''
 					});
 				} else if ( ! pinnedMenuBottom && $adminMenuWrap.offset().top + height.menu < windowPos + height.window ) {
-					// pin the bottom
+					// Pin it to the bottom.
 					pinnedMenuBottom = true;
 					$adminMenuWrap.css({
 						position: 'fixed',
 						top: '',
 						bottom: 0
 					});
 				}
 			} 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 ) {
 						menuTop = windowPos;
 					}
 						position: 'absolute',
 						top: menuTop,
 						bottom: ''
 					});
 				} else if ( ! pinnedMenuTop && $adminMenuWrap.offset().top >= windowPos + height.adminbar ) {
-					// pin the top
+					// Pin it to the top.
 					pinnedMenuTop = true;
 					$adminMenuWrap.css({
 						position: 'fixed',
 						top: '',
 						bottom: ''
 					});
 				}
 			} 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 ) {
 					$adminMenuWrap.css({
 						position: 'absolute',
 		}
 		lastScrollPosition = windowPos;
 	}
+	/**
+	 * Determines the height of certain elements.
+	 *
+	 * @since 4.1.0
+	 *
+	 * @returns {void}
+	 */
 	function resetHeights() {
 		height = {
 			window: $window.height(),
 			wpwrap: $wpwrap.height(),
 			adminbar: $adminbar.height(),
 			menu: $adminMenuWrap.height()
 		};
 	}
+	/**
+	 * Unpins the menu.
+	 *
+	 * @since 4.1.0
+	 *
+	 * @returns {void}
+	 */
 	function unpinMenu() {
 		if ( isIOS || ! menuIsPinned ) {
 			return;
 		}
 			top: '',
 			bottom: ''
 		});
 	}
+	/**
+	 * Pins and unpins the menu when applicable.
+	 *
+	 * @since 4.1.0
+	 *
+	 * @returns {void}
+	 */
 	function setPinMenu() {
 		resetHeights();
 		if ( $adminmenu.data('wp-responsive') ) {
 			$body.removeClass( 'sticky-menu' );
 		$document.on( 'tinymce-editor-init.pin-menu', function( event, editor ) {
 			editor.on( 'wp-autoresize', resetHeights );
 		});
 	}
+	/**
+	 * 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;
 			// Modify functionality based on custom activate/deactivate event
 			$document.on( 'wp-responsive-activate.wp-responsive', function() {
 				self.deactivate();
 			});
 			$( '#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' );
 				if ( $wpwrap.hasClass( 'wp-responsive-open' ) ) {
 					$(this).find('a').attr( 'aria-expanded', 'true' );
 				} else {
 					$(this).find('a').attr( 'aria-expanded', 'false' );
 				}
 			} );
-			// Add menu events
+			// Add menu events.
 			$adminmenu.on( 'click.wp-responsive', 'li.wp-has-submenu > a', function( event ) {
 				if ( ! $adminmenu.data('wp-responsive') ) {
 					return;
 				}
 			});
 			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;
 				if ( width <= 782 ) {
 					self.disableSortables();
 				}
 			});
 		},
+		/**
+		 * 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' );
 			$adminmenu.data( 'wp-responsive', 1 );
 			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();
 			// Exclude IE < 9, it doesn't support @media CSS rules.
 			if ( ! viewportWidth ) {
 			} else {
 				this.disableOverlay();
 			}
 		},
+		/**
+		 * 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>' )
 					.insertAfter( '#wpcontent' )
 					.hide()
 			$toolbarPopups.on( 'click.wp-responsive', function() {
 				$overlay.show();
 			});
 		},
+		/**
+		 * 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');
+					$sortables.sortable( 'disable' );
-				} catch(e) {}
+				} catch ( e ) {}
 			}
 		},
+		/**
+		 * Enables sortables.
+		 *
+		 * @since 3.8.0
+		 *
+		 * @returns {void}
+		 */
 		enableSortables: function() {
 			if ( $sortables.length ) {
 				try {
-					$sortables.sortable('enable');
+					$sortables.sortable( 'enable' );
-				} catch(e) {}
+				} 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' );
 	}
 	$( document ).ajaxComplete( function() {
 		aria_button_if_js();
 	});
 	/**
-	 * @summary Get the viewport width.
+	 * Get the viewport width.
 	 *
 	 * @since 4.7.0
 	 *
 	 * @returns {number|boolean} The current viewport width or false if the
 	 *                           browser doesn't support innerWidth (IE < 9).
 		return viewportWidth;
 	}
 	/**
-	 * @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.
 	 *
 	 * @since 4.7.0
 	// Set the menu state when the window gets resized.
 	$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
 	 * technologies. In the responsive view, the button is always hidden.
 	 *
 		// Toggle the Show Details button expanded state.
 		$( this ).attr( 'aria-expanded', $progressDiv.is( ':visible' ) );
 	});
 });
-// 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 );
 	}

enmi-conf.org