Docs: Improve inline comments per the documentation standards.

Includes minor code layout fixes for better readability.

See #48303.

git-svn-id: https://develop.svn.wordpress.org/trunk@47122 602fd350-edb4-49c9-b593-d223f7449a82

1 files changed, 75 insertions, 73 deletions

diff --git a/src/js/_enqueues/lib/nav-menu.js b/src/js/_enqueues/lib/nav-menu.js
index 95b66c1a42..3a0bd642ef 100644
--- a/src/js/_enqueues/lib/nav-menu.js
+++ b/src/js/_enqueues/lib/nav-menu.js
@@ -69,7 +69,7 @@
 		},
 
 		jQueryExtensions : function() {
-			// jQuery extensions
+			// jQuery extensions.
 			$.fn.extend({
 				menuItemDepth : function() {
 					var margin = api.isRTL ? this.eq(0).css('margin-right') : this.eq(0).css('margin-left');
@@ -114,7 +114,7 @@
 							depth = t.menuItemDepth(),
 							newDepth = depth + dir;
 
-						// Change .menu-item-depth-n class
+						// Change .menu-item-depth-n class.
 						t.moveHorizontally( newDepth, depth );
 					});
 				},
@@ -125,10 +125,10 @@
 							diff = newDepth - depth,
 							subItemText = t.find('.is-submenu');
 
-						// Change .menu-item-depth-n class
+						// Change .menu-item-depth-n class.
 						t.updateDepthClass( newDepth, depth ).updateParentMenuItemDBId();
 
-						// If it has children, move those too
+						// If it has children, move those too.
 						if ( children ) {
 							children.each(function() {
 								var t = $(this),
@@ -138,7 +138,7 @@
 							});
 						}
 
-						// Show "Sub item" helper text
+						// Show "Sub item" helper text.
 						if (0 === newDepth)
 							subItemText.hide();
 						else
@@ -153,7 +153,7 @@
 							parentDepth = depth - 1,
 							parent = item.prevAll( '.menu-item-depth-' + parentDepth ).first();
 
-						if ( 0 === depth ) { // Item is on the top level, has no parent
+						if ( 0 === depth ) { // Item is on the top level, has no parent.
 							input.val(0);
 						} else { // Find the parent item, and retrieve its object id.
 							input.val( parent.find( '.menu-item-data-db-id' ).val() );
@@ -191,10 +191,10 @@
 						if ( !checkboxes.length )
 							return false;
 
-						// Show the ajax spinner
+						// Show the Ajax spinner.
 						t.find( '.button-controls .spinner' ).addClass( 'is-active' );
 
-						// Retrieve menu item data
+						// Retrieve menu item data.
 						$(checkboxes).each(function(){
 							var t = $(this),
 								listItemDBIDMatch = re.exec( t.attr('name') ),
@@ -205,9 +205,9 @@
 							menuItems[listItemDBID] = t.closest('li').getItemData( 'add-menu-item', listItemDBID );
 						});
 
-						// Add the items
+						// Add the items.
 						api.addItemToMenu(menuItems, processMethod, function(){
-							// Deselect the items and hide the ajax spinner
+							// Deselect the items and hide the Ajax spinner.
 							checkboxes.prop( 'checked', false );
 							t.find( '.button-controls .select-all' ).prop( 'checked', false );
 							t.find( '.button-controls .spinner' ).removeClass( 'is-active' );
@@ -312,22 +312,22 @@
 			case 'up':
 				newItemPosition = thisItemPosition - 1;
 
-				// Already at top
+				// Already at top.
 				if ( 0 === thisItemPosition )
 					break;
 
-				// If a sub item is moved to top, shift it to 0 depth
+				// If a sub item is moved to top, shift it to 0 depth.
 				if ( 0 === newItemPosition && 0 !== thisItemDepth )
 					thisItem.moveHorizontally( 0, thisItemDepth );
 
-				// If prev item is sub item, shift to match depth
+				// If prev item is sub item, shift to match depth.
 				if ( 0 !== prevItemDepth )
 					thisItem.moveHorizontally( prevItemDepth, thisItemDepth );
 
 				// Does this item have sub items?
 				if ( thisItemChildren ) {
 					items = thisItem.add( thisItemChildren );
-					// Move the entire block
+					// Move the entire block.
 					items.detach().insertBefore( menuItems.eq( newItemPosition ) ).updateParentMenuItemDBId();
 				} else {
 					thisItem.detach().insertBefore( menuItems.eq( newItemPosition ) ).updateParentMenuItemDBId();
@@ -351,40 +351,40 @@
 
 					items.detach().insertAfter( menuItems.eq( thisItemPosition + items.length ) ).updateParentMenuItemDBId();
 				} else {
-					// If next item has sub items, shift depth
+					// If next item has sub items, shift depth.
 					if ( 0 !== nextItemChildren.length )
 						thisItem.moveHorizontally( nextItemDepth, thisItemDepth );
 
-					// Have we reached the bottom
+					// Have we reached the bottom?
 					if ( menuItemsCount === thisItemPosition + 1 )
 						break;
 					thisItem.detach().insertAfter( menuItems.eq( thisItemPosition + 1 ) ).updateParentMenuItemDBId();
 				}
 				break;
 			case 'top':
-				// Already at top
+				// Already at top.
 				if ( 0 === thisItemPosition )
 					break;
 				// Does this item have sub items?
 				if ( thisItemChildren ) {
 					items = thisItem.add( thisItemChildren );
-					// Move the entire block
+					// Move the entire block.
 					items.detach().insertBefore( menuItems.eq( 0 ) ).updateParentMenuItemDBId();
 				} else {
 					thisItem.detach().insertBefore( menuItems.eq( 0 ) ).updateParentMenuItemDBId();
 				}
 				break;
 			case 'left':
-				// As far left as possible
+				// As far left as possible.
 				if ( 0 === thisItemDepth )
 					break;
 				thisItem.shiftHorizontally( -1 );
 				break;
 			case 'right':
-				// Can't be sub item at top
+				// Can't be sub item at top.
 				if ( 0 === thisItemPosition )
 					break;
-				// Already sub item of prevItem
+				// Already sub item of prevItem.
 				if ( thisItemData['menu-item-parent-id'] === prevItemId )
 					break;
 				thisItem.shiftHorizontally( 1 );
@@ -402,7 +402,7 @@
 			api.refreshKeyboardAccessibility();
 			api.refreshAdvancedAccessibility();
 
-			// Refresh the accessibility when the user comes close to the item in any way
+			// Refresh the accessibility when the user comes close to the item in any way.
 			menu.on( 'mouseenter.refreshAccessibility focus.refreshAccessibility touchstart.refreshAccessibility' , '.menu-item' , function(){
 				api.refreshAdvancedAccessibilityOfItem( $( this ).find( 'a.item-edit' ) );
 			} );
@@ -412,7 +412,7 @@
 				api.refreshAdvancedAccessibilityOfItem( $( this ) );
 			} );
 
-			// Links for moving items
+			// Links for moving items.
 			menu.on( 'click', '.menus-move', function () {
 				var $this = $( this ),
 					dir = $this.data( 'dir' );
@@ -433,7 +433,7 @@
 		 */
 		refreshAdvancedAccessibilityOfItem : function( itemToRefresh ) {
 
-			// Only refresh accessibility when necessary
+			// Only refresh accessibility when necessary.
 			if ( true !== $( itemToRefresh ).data( 'needs_accessibility_refresh' ) ) {
 				return;
 			}
@@ -494,7 +494,7 @@
 				itemPosition = primaryItems.index( menuItem ) + 1,
 				totalMenuItems = primaryItems.length,
 
-				// String together help text for primary menu items
+				// String together help text for primary menu items.
 				title = menus.menuFocus.replace( '%1$s', itemName ).replace( '%2$d', itemPosition ).replace( '%3$d', totalMenuItems );
 			} else {
 				parentItem = menuItem.prevAll( '.menu-item-depth-' + parseInt( depth - 1, 10 ) ).first(),
@@ -503,13 +503,13 @@
 				subItems = $( '.menu-item .menu-item-data-parent-id[value="' + parentItemId + '"]' ),
 				itemPosition = $( subItems.parents('.menu-item').get().reverse() ).index( menuItem ) + 1;
 
-				// String together help text for sub menu items
+				// String together help text for sub menu items.
 				title = menus.subMenuFocus.replace( '%1$s', itemName ).replace( '%2$d', itemPosition ).replace( '%3$s', parentItemName );
 			}
 
 			$this.attr( 'aria-label', title );
 
-			// Mark this item's accessibility as refreshed
+			// Mark this item's accessibility as refreshed.
 			$this.data( 'needs_accessibility_refresh', false );
 		},
 
@@ -523,10 +523,10 @@
 			// Hide all the move buttons by default.
 			$( '.menu-item-settings .field-move .menus-move' ).hide();
 
-			// Mark all menu items as unprocessed
+			// Mark all menu items as unprocessed.
 			$( 'a.item-edit' ).data( 'needs_accessibility_refresh', true );
 
-			// All open items have to be refreshed or they will show no links
+			// All open items have to be refreshed or they will show no links.
 			$( '.menu-item-edit-active a.item-edit' ).each( function() {
 				api.refreshAdvancedAccessibilityOfItem( this );
 			} );
@@ -541,18 +541,18 @@
 						thisItem = $this.parents( 'li.menu-item' ),
 						thisItemData = thisItem.getItemData();
 
-					// Bail if it's not an arrow key
+					// Bail if it's not an arrow key.
 					if ( 37 != e.which && 38 != e.which && 39 != e.which && 40 != e.which )
 						return;
 
-					// Avoid multiple keydown events
+					// Avoid multiple keydown events.
 					$this.off('keydown');
 
-					// Bail if there is only one menu item
+					// Bail if there is only one menu item.
 					if ( 1 === $('#menu-to-edit li').length )
 						return;
 
-					// If RTL, swap left/right arrows
+					// If RTL, swap left/right arrows.
 					arrows = { '38': 'up', '40': 'down', '37': 'left', '39': 'right' };
 					if ( $('body').hasClass('rtl') )
 						arrows = { '38' : 'up', '40' : 'down', '39' : 'left', '37' : 'right' };
@@ -571,7 +571,7 @@
 						api.moveMenuItem( $this, 'right' );
 						break;
 					}
-					// Put focus back on same menu item
+					// Put focus back on same menu item.
 					$( '#edit-' + thisItemData['menu-item-db-id'] ).focus();
 					return false;
 				});
@@ -594,10 +594,10 @@
 		},
 
 		initToggles : function() {
-			// init postboxes
+			// Init postboxes.
 			postboxes.add_postbox_toggles('nav-menus');
 
-			// adjust columns functions for menus UI
+			// Adjust columns functions for menus UI.
 			columns.useCheckboxesForHidden();
 			columns.checked = function(field) {
 				$('.field-' + field).removeClass('hidden-field');
@@ -605,7 +605,7 @@
 			columns.unchecked = function(field) {
 				$('.field-' + field).addClass('hidden-field');
 			};
-			// hide fields
+			// Hide fields.
 			api.menuList.hideAdvancedMenuItemFields();
 
 			$('.hide-postbox-tog').click(function () {
@@ -639,7 +639,7 @@
 				start: function(e, ui) {
 					var height, width, parent, children, tempHolder;
 
-					// handle placement for rtl orientation
+					// Handle placement for RTL orientation.
 					if ( api.isRTL )
 						ui.item[0].style.right = 'auto';
 
@@ -649,19 +649,19 @@
 					originalDepth = ui.item.menuItemDepth();
 					updateCurrentDepth(ui, originalDepth);
 
-					// Attach child elements to parent
-					// Skip the placeholder
+					// Attach child elements to parent.
+					// Skip the placeholder.
 					parent = ( ui.item.next()[0] == ui.placeholder[0] ) ? ui.item.next() : ui.item;
 					children = parent.childMenuItems();
 					transport.append( children );
 
 					// Update the height of the placeholder to match the moving item.
 					height = transport.outerHeight();
-					// If there are children, account for distance between top of children and parent
+					// If there are children, account for distance between top of children and parent.
 					height += ( height > 0 ) ? (ui.placeholder.css('margin-top').slice(0, -2) * 1) : 0;
 					height += ui.helper.outerHeight();
 					helperHeight = height;
-					height -= 2; // Subtract 2 for borders
+					height -= 2;                                              // Subtract 2 for borders.
 					ui.placeholder.height(height);
 
 					// Update the width of the placeholder to match the moving item.
@@ -670,18 +670,18 @@
 						var depth = $(this).menuItemDepth();
 						maxChildDepth = (depth > maxChildDepth) ? depth : maxChildDepth;
 					});
-					width = ui.helper.find('.menu-item-handle').outerWidth(); // Get original width
-					width += api.depthToPx(maxChildDepth - originalDepth); // Account for children
-					width -= 2; // Subtract 2 for borders
+					width = ui.helper.find('.menu-item-handle').outerWidth(); // Get original width.
+					width += api.depthToPx(maxChildDepth - originalDepth);    // Account for children.
+					width -= 2;                                               // Subtract 2 for borders.
 					ui.placeholder.width(width);
 
 					// Update the list of menu items.
 					tempHolder = ui.placeholder.next( '.menu-item' );
-					tempHolder.css( 'margin-top', helperHeight + 'px' ); // Set the margin to absorb the placeholder
-					ui.placeholder.detach(); // detach or jQuery UI will think the placeholder is a menu item
-					$(this).sortable( 'refresh' ); // The children aren't sortable. We should let jQ UI know.
-					ui.item.after( ui.placeholder ); // reattach the placeholder.
-					tempHolder.css('margin-top', 0); // reset the margin
+					tempHolder.css( 'margin-top', helperHeight + 'px' ); // Set the margin to absorb the placeholder.
+					ui.placeholder.detach();         // Detach or jQuery UI will think the placeholder is a menu item.
+					$(this).sortable( 'refresh' );   // The children aren't sortable. We should let jQuery UI know.
+					ui.item.after( ui.placeholder ); // Reattach the placeholder.
+					tempHolder.css('margin-top', 0); // Reset the margin.
 
 					// Now that the element is complete, we can update...
 					updateSharedVars(ui);
@@ -690,31 +690,31 @@
 					var children, subMenuTitle,
 						depthChange = currentDepth - originalDepth;
 
-					// Return child elements to the list
+					// Return child elements to the list.
 					children = transport.children().insertAfter(ui.item);
 
-					// Add "sub menu" description
+					// Add "sub menu" description.
 					subMenuTitle = ui.item.find( '.item-title .is-submenu' );
 					if ( 0 < currentDepth )
 						subMenuTitle.show();
 					else
 						subMenuTitle.hide();
 
-					// Update depth classes
+					// Update depth classes.
 					if ( 0 !== depthChange ) {
 						ui.item.updateDepthClass( currentDepth );
 						children.shiftDepthClass( depthChange );
 						updateMenuMaxDepth( depthChange );
 					}
-					// Register a change
+					// Register a change.
 					api.registerChange();
 					// Update the item data.
 					ui.item.updateParentMenuItemDBId();
 
-					// address sortable's incorrectly-calculated top in opera
+					// Address sortable's incorrectly-calculated top in Opera.
 					ui.item[0].style.top = 0;
 
-					// handle drop placement for rtl orientation
+					// Handle drop placement for rtl orientation.
 					if ( api.isRTL ) {
 						ui.item[0].style.left = 'auto';
 						ui.item[0].style.right = 0;
@@ -736,9 +736,11 @@
 						edge = api.isRTL ? offset.left + ui.helper.width() : offset.left,
 						depth = api.negateIfRTL * api.pxToDepth( edge - menuEdge );
 
-					// Check and correct if depth is not within range.
-					// Also, if the dragged element is dragged upwards over
-					// an item, shift the placeholder to a child position.
+					/*
+					 * Check and correct if depth is not within range.
+					 * Also, if the dragged element is dragged upwards over an item,
+					 * shift the placeholder to a child position.
+					 */
 					if ( depth > maxDepth || offset.top < ( prevBottom - api.options.targetTolerance ) ) {
 						depth = maxDepth;
 					} else if ( depth < minDepth ) {
@@ -748,7 +750,7 @@
 					if( depth != currentDepth )
 						updateCurrentDepth(ui, depth);
 
-					// If we overlap the next element, manually shift downwards
+					// If we overlap the next element, manually shift downwards.
 					if( nextThreshold && offset.top + helperHeight > nextThreshold ) {
 						next.after( ui.placeholder );
 						updateSharedVars( ui );
@@ -955,12 +957,12 @@
 				return false;
 			}
 
-			// Show the ajax spinner
+			// Show the Ajax spinner.
 			$( '.customlinkdiv .spinner' ).addClass( 'is-active' );
 			this.addLinkToMenu( url, label, processMethod, function() {
-				// Remove the ajax spinner
+				// Remove the Ajax spinner.
 				$( '.customlinkdiv .spinner' ).removeClass( 'is-active' );
-				// Set custom link form back to defaults
+				// Set custom link form back to defaults.
 				$('#custom-menu-item-name').val('').blur();
 				$( '#custom-menu-item-url' ).val( '' ).attr( 'placeholder', 'https://' );
 			});
@@ -997,10 +999,10 @@
 			$.post( ajaxurl, params, function(menuMarkup) {
 				var ins = $('#menu-instructions');
 
-				menuMarkup = $.trim( menuMarkup ); // Trim leading whitespaces
+				menuMarkup = $.trim( menuMarkup ); // Trim leading whitespaces.
 				processMethod(menuMarkup, params);
 
-				// Make it stand out a bit more visually, by adding a fadeIn
+				// Make it stand out a bit more visually, by adding a fadeIn.
 				$( 'li.pending' ).hide().fadeIn('slow');
 				$( '.drag-instructions' ).show();
 				if( ! ins.hasClass( 'menu-instructions-inactive' ) && ins.siblings().length )
@@ -1051,7 +1053,7 @@
 						return navMenuL10n.saveAlert;
 				};
 			} else {
-				// Make the post boxes read-only, as they can't be used yet
+				// Make the post boxes read-only, as they can't be used yet.
 				$( '#menu-settings-column' ).find( 'input,select' ).end().find( 'a' ).attr( 'href', '#' ).unbind( 'click' );
 			}
 		},
@@ -1071,7 +1073,7 @@
 
 					wrapper = target.parents('.accordion-section-content').first();
 
-					// upon changing tabs, we want to uncheck all checkboxes
+					// Upon changing tabs, we want to uncheck all checkboxes.
 					$( 'input', wrapper ).prop( 'checked', false );
 
 					$('.tabs-panel-active', wrapper).removeClass('tabs-panel-active').addClass('tabs-panel-inactive');
@@ -1080,7 +1082,7 @@
 					$('.tabs', wrapper).removeClass('tabs');
 					target.parent().addClass('tabs');
 
-					// select the search bar
+					// Select the search bar.
 					$('.quick-search', wrapper).focus();
 
 					// Hide controls in the search tab if no items found.
@@ -1193,17 +1195,17 @@
 			var locs = '',
 			menuName = $('#menu-name'),
 			menuNameVal = menuName.val();
-			// Cancel and warn if invalid menu name
+			// Cancel and warn if invalid menu name.
 			if ( ! menuNameVal || ! menuNameVal.replace( /\s+/, '' ) ) {
 				menuName.parent().addClass( 'form-invalid' );
 				return false;
 			}
-			// Copy menu theme locations
+			// Copy menu theme locations.
 			$('#nav-menu-theme-locations select').each(function() {
 				locs += '<input type="hidden" name="' + this.name + '" value="' + $(this).val() + '" />';
 			});
 			$('#update-nav-menu').append( locs );
-			// Update menu item position data
+			// Update menu item position data.
 			api.menuList.find('.menu-item-data-position').val( function(index) { return index + 1; } );
 			window.onbeforeunload = null;
 
@@ -1211,7 +1213,7 @@
 		},
 
 		eventOnClickMenuDelete : function() {
-			// Delete warning AYS
+			// Delete warning AYS.
 			if ( window.confirm( navMenuL10n.warnDeleteMenu ) ) {
 				window.onbeforeunload = null;
 				return true;
@@ -1253,7 +1255,7 @@
 			$items.each(function(){
 				$item = $(this);
 
-				// make a unique DB ID number
+				// Make a unique DB ID number.
 				matched = pattern.exec($item.html());
 
 				if ( matched && matched[1] ) {