WordPress.org

Make WordPress Core

Changeset 43332


Ignore:
Timestamp:
06/07/2018 02:39:43 PM (3 years ago)
Author:
atimmer
Message:

Docs: Improve JSDoc for admin-bar.js.

Props manuelaugustin, terwdan, sjardo, LisanneKluitmans.
Fixes #43871.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/js/_enqueues/lib/admin-bar.js

    r43309 r43332  
    1111        var adminbar = $('#wpadminbar'), refresh, touchOpen, touchClose, disableHoverIntent = false;
    1212
    13         refresh = function(i, el){ // force the browser to refresh the tabbing index
     13        /**
     14         * Forces the browser to refresh the tabbing index.
     15         *
     16         * @since 3.3.0
     17         *
     18         * @param {number}      i  The index of the HTML element to remove the tab index
     19         *                         from. This parameter is necessary because we use this
     20         *                         function in .each calls.
     21         * @param {HTMLElement} el The HTML element to remove the tab index from.
     22         *
     23         * @return {void}
     24         */
     25        refresh = function(i, el){
    1426            var node = $(el), tab = node.attr('tabindex');
    1527            if ( tab )
     
    1729        };
    1830
     31        /**
     32         * Adds or removes the hover class on touch.
     33         *
     34         * @since 3.5.0
     35         *
     36         * @param {boolean} unbind If true removes the wp-mobile-hover class.
     37         *
     38         * @return {void}
     39         */
    1940        touchOpen = function(unbind) {
    2041            adminbar.find('li.menupop').on('click.wp-mobile-hover', function(e) {
     
    4465        };
    4566
     67        /**
     68         * Removes the hover class if clicked or touched outside the admin bar.
     69         *
     70         * @since 3.5.0
     71         *
     72         * @return {void}
     73         */
    4674        touchClose = function() {
    4775            var mobileEvent = /Mobile\/.+Safari/.test(navigator.userAgent) ? 'touchstart' : 'click';
     
    5583        adminbar.removeClass('nojq').removeClass('nojs');
    5684
     85        // If clicked on the adminbar add the hoverclass, if clicked outside it remove
     86        // it.
    5787        if ( 'ontouchstart' in window ) {
    5888            adminbar.on('touchstart', function(){
     
    6696        }
    6797
     98        // Adds or removes the hover class based on the hover intent.
    6899        adminbar.find('li.menupop').hoverIntent({
    69100            over: function() {
     
    84115        });
    85116
     117        // Prevents the toolbar from covering up content when a hash is present in the
     118        // URL.
    86119        if ( window.location.hash )
    87120            window.scrollBy( 0, -32 );
    88121
     122        /**
     123         * Handles the selected state of the Shortlink link.
     124         *
     125         * When the input is visible the link should be selected, when the input is
     126         * unfocused the link should be unselected.
     127         *
     128         * @param {Object} e The click event.
     129         *
     130         * @return {void}
     131         **/
    89132        $('#wp-admin-bar-get-shortlink').click(function(e){
    90133            e.preventDefault();
     
    94137        });
    95138
     139        /**
     140         * Removes the hoverclass if the enter key is pressed.
     141         *
     142         * Makes sure the tab index is refreshed by refreshing each ab-item
     143         * and its children.
     144         *
     145         * @param {Object} e The keydown event.
     146         *
     147         * @return {void}
     148         */
    96149        $('#wpadminbar li.menupop > .ab-item').bind('keydown.adminbar', function(e){
     150            // Key code 13 is the enter key.
    97151            if ( e.which != 13 )
    98152                return;
     
    117171        }).each(refresh);
    118172
     173        /**
     174         * Removes the hover class when the escape key is pressed.
     175         *
     176         * Makes sure the tab index is refreshed by refreshing each ab-item
     177         * and its children.
     178         *
     179         * @param {Object} e The keydown event.
     180         *
     181         * @return {void}
     182         */
    119183        $('#wpadminbar .ab-item').bind('keydown.adminbar', function(e){
     184            // Key code 27 is the escape key.
    120185            if ( e.which != 27 )
    121186                return;
     
    130195        });
    131196
     197        /**
     198         * Scrolls to top of page by clicking the adminbar.
     199         *
     200         * @param {Object} e The click event.
     201         *
     202         * @return {void}
     203         */
    132204        adminbar.click( function(e) {
    133205            if ( e.target.id != 'wpadminbar' && e.target.id != 'wp-admin-bar-top-secondary' ) {
     
    140212        });
    141213
    142         // fix focus bug in WebKit
     214        /**
     215         * Sets the focus on an element with a href attribute.
     216         *
     217         * The timeout is used to fix a focus bug in WebKit.
     218         *
     219         * @param {Object} e The keydown event.
     220         *
     221         * @return {void}
     222         */
    143223        $('.screen-reader-shortcut').keydown( function(e) {
    144224            var id, ua;
     
    159239
    160240        $( '#adminbar-search' ).on({
     241            /**
     242             * Adds the adminbar-focused class on focus.
     243             *
     244             * @return {void}
     245             */
    161246            focus: function() {
    162247                $( '#adminbarsearch' ).addClass( 'adminbar-focused' );
     248            /**
     249             * Removes the adminbar-focused class on blur.
     250             *
     251             * @return {void}
     252             */
    163253            }, blur: function() {
    164254                $( '#adminbarsearch' ).removeClass( 'adminbar-focused' );
     
    166256        } );
    167257
    168         // Empty sessionStorage on logging out
    169258        if ( 'sessionStorage' in window ) {
     259            /**
     260             * Empties sessionStorage on logging out.
     261             *
     262             * @return {void}
     263             */
    170264            $('#wp-admin-bar-logout a').click( function() {
    171265                try {
     
    185279    });
    186280} else {
     281    /**
     282     * Wrapper function for the adminbar that's used if jQuery isn't available.
     283     *
     284     * @param {Object} d The document object.
     285     * @param {Object} w The window object.
     286     *
     287     * @return {void}
     288     */
    187289    (function(d, w) {
     290        /**
     291         * Adds an event listener to an object.
     292         *
     293         * @since 3.1.0
     294         *
     295         * @param {Object}   obj  The object to add the event listener to.
     296         * @param {string}   type The type of event.
     297         * @param {function} fn   The function to bind to the event listener.
     298         *
     299         * @return {void}
     300         */
    188301        var addEvent = function( obj, type, fn ) {
    189302            if ( obj.addEventListener )
     
    197310
    198311        /**
    199          * Get the timeout ID of the given element
     312         * Gets the timeout ID of the given element.
     313         *
     314         * @since 3.1.0
     315         *
     316         * @param {HTMLElement} el The HTML element.
     317         *
     318         * @return {number|boolean} The ID value of the timer that is set or false.
    200319         */
    201320        getTOID = function(el) {
     
    208327        },
    209328
     329        /**
     330         * Adds the hoverclass to menu items.
     331         *
     332         * @since 3.1.0
     333         *
     334         * @param {HTMLElement} t The HTML element.
     335         *
     336         * @return {void}
     337         */
    210338        addHoverClass = function(t) {
    211339            var i, id, inA, hovering, ul, li,
     
    213341                ancestorLength = 0;
    214342
     343            // aB is adminbar. d is document.
    215344            while ( t && t != aB && t != d ) {
    216345                if ( 'LI' == t.nodeName.toUpperCase() ) {
     
    225354            }
    226355
    227             // Remove any selected classes.
     356            // Removes any selected classes.
    228357            if ( hovering && hovering.parentNode ) {
    229358                ul = hovering.parentNode;
     
    238367            }
    239368
    240             /* remove the hover class for any objects not in the immediate element's ancestry */
     369            // Removes the hover class for any objects not in the immediate element's ancestry.
    241370            i = q.length;
    242371            while ( i-- ) {
     
    253382        },
    254383
     384        /**
     385         * Removes the hoverclass from menu items.
     386         *
     387         * @since 3.1.0
     388         *
     389         * @param {HTMLElement} t The HTML element.
     390         *
     391         * @return {void}
     392         */
    255393        removeHoverClass = function(t) {
    256394            while ( t && t != aB && t != d ) {
     
    267405        },
    268406
     407        /**
     408         * Handles the click on the Shortlink link in the adminbar.
     409         *
     410         * @since 3.1.0
     411         *
     412         * @param {HTMLElement} e The HTML element.
     413         *
     414         * @return {boolean} Returns false to prevent default click behavior.
     415         */
    269416        clickShortlink = function(e) {
    270417            var i, l, node,
     
    305452        },
    306453
     454        /**
     455         * Scrolls to the top of the page.
     456         *
     457         * @since 3.4.0
     458         *
     459         * @param {HTMLElement} t The HTML element.
     460         *
     461         * @return {void}
     462         */
    307463        scrollToTop = function(t) {
    308464            var distance, speed, step, steps, timer, speed_step;
Note: See TracChangeset for help on using the changeset viewer.