Ticket #43871: admin-bar.diff

src/wp-includes/js/admin-bar.js

@@ -10 +10 @@
         jQuery(document).ready(function($){
                 var adminbar = $('#wpadminbar'), refresh, touchOpen, touchClose, disableHoverIntent = false;
 
-                refresh = function(i, el){ // force the browser to refresh the tabbing index
+                /**
+                 * Forces the browser to refresh the tabbing index.
+                 *
+                 * @since 3.5.0
+                 *
+                 * @param  {integer} i The index of the HTML element to remove the tab index from.
+                 * @param {HTMLElement} el The HTML element to remove the tab index from.
+                 *
+                 * @returns {void}
+                 */
+                refresh = function(i, el){
                         var node = $(el), tab = node.attr('tabindex');
                         if ( tab )
                                 node.attr('tabindex', '0').attr('tabindex', tab);
                 };
 
+                /**
+                 * Adds or removes the hover class on touch.
+                 *
+                 * @since 3.5.0
+                 *
+                 * @param {bool} unbind If true removes the wp-mobile-hover class.
+                 *
+                 * @returns {void}
+                 */
                 touchOpen = function(unbind) {
                         adminbar.find('li.menupop').on('click.wp-mobile-hover', function(e) {
                                 var el = $(this);
@@ -43 +62 @@
                         });
                 };
 
+                /**
+                 * Removes the hover class if clicked or touched outside the adminbar.
+                 *
+                 * @since 3.5.0
+                 *
+                 * @returns {void}
+                 */
                 touchClose = function() {
                         var mobileEvent = /Mobile\/.+Safari/.test(navigator.userAgent) ? 'touchstart' : 'click';
                         // close any open drop-downs when the click/touch is not on the toolbar
@@ -54 +80 @@
 
                 adminbar.removeClass('nojq').removeClass('nojs');
 
+                // If clicked on the adminbar add the hoverclass, if clicked outside it remove it.
                 if ( 'ontouchstart' in window ) {
                         adminbar.on('touchstart', function(){
                                 touchOpen(true);
@@ -65 +92 @@
                         touchClose();
                 }
 
+                // Adds or remove the hover class based on the hover intent.
                 adminbar.find('li.menupop').hoverIntent({
                         over: function() {
                                 if ( disableHoverIntent )
@@ -83 +111 @@
                         interval: 100
                 });
 
+                // Prevents the toolbar from covering up content when a hash is present in the URL.
                 if ( window.location.hash )
                         window.scrollBy( 0, -32 );
 
+                /**
+                 * Adds selected class to shortlink in admin bar.
+                 *
+                 * Removes the selected class from the parents of the selected shortlink-input.
+                 *
+                 * @since 3.5.0
+                 *
+                 * @param {event} e The click event.
+                 *
+                 * @returns {void}
+                 **/
                 $('#wp-admin-bar-get-shortlink').click(function(e){
                         e.preventDefault();
                         $(this).addClass('selected').children('.shortlink-input').blur(function(){
@@ -93 +133 @@
                         }).focus().select();
                 });
 
+                /**
+                 * It removes the hoverclass if the enter key is pressed.
+                 *
+                 * Makes sure the tab index is refreshed by refreshing each ab-item
+                 * and its children.
+                 *
+                 * @since 3.5.0
+                 *
+                 * @param {event} e The keydown event.
+                 *
+                 * @returns {void}
+                 */
                 $('#wpadminbar li.menupop > .ab-item').bind('keydown.adminbar', function(e){
+                        // Key code 13 is the enter key.
                         if ( e.which != 13 )
                                 return;
 
@@ -116 +169 @@
                         target.siblings('.ab-sub-wrapper').find('.ab-item').each(refresh);
                 }).each(refresh);
 
+                /**
+                 * Removes the hover class when the escape key is pressed.
+                 *
+                 * Makes sure the tab index is refreshed by refreshing each ab-item
+                 * and its children.
+                 *
+                 * @since 3.5.0
+                 *
+                 * @param {event} e The keydown event.
+                 *
+                 * @returns {void}
+                 */
                 $('#wpadminbar .ab-item').bind('keydown.adminbar', function(e){
+                        // Key code 27 is the escape key.
                         if ( e.which != 27 )
                                 return;
 
@@ -129 +195 @@
                         target.siblings('.ab-sub-wrapper').find('.ab-item').each(refresh);
                 });
 
+                /**
+                 * Scrolls to top of page by clicking the adminbar.
+                 *
+                 * @since 4.3.0
+                 *
+                 * @param {event} e The click event.
+                 *
+                 * @returns {void}
+                 */
                 adminbar.click( function(e) {
                         if ( e.target.id != 'wpadminbar' && e.target.id != 'wp-admin-bar-top-secondary' ) {
                                 return;
@@ -139 +214 @@
                         e.preventDefault();
                 });
 
-                // fix focus bug in WebKit
+                /**
+                 * Sets the focus on an element with a href attribute.
+                 *
+                 * The timeout is used to fix a focus bug in WebKit.
+                 *
+                 * @since 3.5.0
+                 *
+                 * @param {event} e The keydown event.
+                 *
+                 * @returns {void}
+                 */
                 $('.screen-reader-shortcut').keydown( function(e) {
                         var id, ua;
 
@@ -158 +243 @@
                 });
 
                 $( '#adminbar-search' ).on({
+                        /**
+                         * Adds the adminbar-focused class on focus.
+                         *
+                         * @since 4.2.0
+                         *
+                         * @returns {void}
+                         */
                         focus: function() {
                                 $( '#adminbarsearch' ).addClass( 'adminbar-focused' );
+                        /**
+                         * Remove the adminbar-focused class on blur.
+                         *
+                         * @since 4.2.0
+                         *
+                         * @returns {void}
+                         */
                         }, blur: function() {
                                 $( '#adminbarsearch' ).removeClass( 'adminbar-focused' );
                         }
                 } );
 
-                // Empty sessionStorage on logging out
                 if ( 'sessionStorage' in window ) {
+            /**
+                         * Empties sessionStorage on logging out.
+                         *
+                         * @since 3.6.0
+                         *
+                         * @returns {void}
+             */
                         $('#wp-admin-bar-logout a').click( function() {
                                 try {
                                         for ( var key in sessionStorage ) {
@@ -184 +289 @@
                 }
         });
 } else {
+    /**
+         * Wrapper function for the adminbar that's used if jQuery isn't available.
+         *
+         * @since 3.5.0
+         *
+         * @param {Object} d The document object.
+         * @param {Object} w The window object.
+         *
+         * @returns {void}
+     */
         (function(d, w) {
+        /**
+                 * Adds an event listener to an object.
+                 *
+                 * @since 3.5.0
+                 *
+         * @param {Object} obj The object to add the event listener to.
+         * @param {string} type The type of event.
+         * @param {function} fn The function to bind to the event listener.
+                 *
+                 * @returns {void}
+         */
                 var addEvent = function( obj, type, fn ) {
                         if ( obj.addEventListener )
                                 obj.addEventListener(type, fn, false);
@@ -195 +321 @@
                 aB, hc = new RegExp('\\bhover\\b', 'g'), q = [],
                 rselected = new RegExp('\\bselected\\b', 'g'),
 
-                /**
-                 * Get the timeout ID of the given element
+            /**
+                 * Gets the timeout ID of the given element.
+                 *
+                 * @since 3.5.0
+                 *
+                 * @param {HTMLElement} el The HTML element.
+             *
+                 * @returns {number|boolean} The ID value of the timer that is set or false.
                  */
                 getTOID = function(el) {
                         var i = q.length;
@@ -207 +339 @@
                         return false;
                 },
 
+            /**
+                 * Adds the hoverclass to menu items.
+                 *
+                 * @since 3.5.0
+                 *
+                 * @param {HTMLElement} t The HTML element.
+                 *
+                 * @returns {void}
+                 */
                 addHoverClass = function(t) {
                         var i, id, inA, hovering, ul, li,
                                 ancestors = [],
                                 ancestorLength = 0;
 
+                        // aB is adminbar. d is document.
                         while ( t && t != aB && t != d ) {
                                 if ( 'LI' == t.nodeName.toUpperCase() ) {
                                         ancestors[ ancestors.length ] = t;
@@ -224 +366 @@
                                 t = t.parentNode;
                         }
 
-                        // Remove any selected classes.
+                        // Removes any selected classes.
                         if ( hovering && hovering.parentNode ) {
                                 ul = hovering.parentNode;
                                 if ( ul && 'UL' == ul.nodeName.toUpperCase() ) {
@@ -237 +379 @@
                                 }
                         }
 
-                        /* remove the hover class for any objects not in the immediate element's ancestry */
+                        // Removes the hover class for any objects not in the immediate element's ancestry.
                         i = q.length;
                         while ( i-- ) {
                                 inA = false;
@@ -252 +394 @@
                         }
                 },
 
+                /**
+                         * Removes the hoverclass from menu items.
+                         *
+                         * @since 3.5.0
+                         *
+                         * @param {HTMLElement} t The HTML element.
+                         *
+                         * @returns {void}
+                         */
                 removeHoverClass = function(t) {
                         while ( t && t != aB && t != d ) {
                                 if ( 'LI' == t.nodeName.toUpperCase() ) {
@@ -266 +417 @@
                         }
                 },
 
+                /**
+                 * Handles the click on a shortlink in the adminbar.
+                 *
+                 * @since 3.5.0
+                 *
+                 * @param {HTMLElement} e The HTML element.
+                 *
+                 * @returns {boolean}
+                 */
                 clickShortlink = function(e) {
                         var i, l, node,
                                 t = e.target || e.srcElement;
@@ -304 +464 @@
                         return false;
                 },
 
+                /**
+                 * Scrolls to the top of the page.
+                 *
+                 * @since 3.5.0
+                 *
+                 * @param {HTMLElement} t The HTML element.
+                 * 
+                 * @returns {void}
+                 */
                 scrollToTop = function(t) {
                         var distance, speed, step, steps, timer, speed_step;