WordPress.org

Make WordPress Core

Changeset 42351


Ignore:
Timestamp:
12/03/17 18:10:21 (9 days ago)
Author:
adamsilverstein
Message:

Docs: Improve JSDocs for common.js.

Props andizer, rensw90, benvaassen, jipmoors, ireneyoast and nicollle.
Fixes 42679.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-admin/js/common.js

    r42012 r42351  
    11/* global setUserSetting, ajaxurl, commonL10n, alert, confirm, pagenow */ 
    22var showNotice, adminMenu, columns, validateForm, screenMeta; 
     3 
     4/** 
     5 *  @summary Adds common WordPress functionality to the window. 
     6 * 
     7 *  @param {jQuery} $        jQuery object. 
     8 *  @param {Object} window   The window object. 
     9 *  @param {mixed} undefined Unused. 
     10 */ 
    311( function( $, window, undefined ) { 
    412    var $document = $( document ), 
     
    614        $body = $( document.body ); 
    715 
    8 // Removed in 3.3. 
    9 // (perhaps) needed for back-compat 
     16/** 
     17 * @summary Removed in 3.3.0, needed for back-compatibility. 
     18 * 
     19 * @since 2.7.0 
     20 * @deprecated 3.3.0 
     21 */ 
    1022adminMenu = { 
    1123    init : function() {}, 
     
    1628}; 
    1729 
    18 // show/hide/save table columns 
     30// Show/hide/save table columns. 
    1931columns = { 
     32 
     33    /** 
     34     * @summary Initializes the column toggles in the screen options. 
     35     * 
     36     * Binds an onClick event to the checkboxes to show or hide the table columns 
     37     * based on their toggled state. And persists the toggled state. 
     38     * 
     39     * @since 2.7.0 
     40     * 
     41     * @returns {void} 
     42     */ 
    2043    init : function() { 
    2144        var that = this; 
     
    3154    }, 
    3255 
     56    /** 
     57     * @summary Saves the toggled state for the columns. 
     58     * 
     59     * Saves whether the columns should be shown or hidden on a page. 
     60     * 
     61     * @since 3.0.0 
     62     * 
     63     * @returns {void} 
     64     */ 
    3365    saveManageColumnsState : function() { 
    3466        var hidden = this.hidden(); 
     
    4173    }, 
    4274 
     75    /** 
     76     * @summary Makes a column visible and adjusts the column span for the table. 
     77     * 
     78     * @since 3.0.0 
     79     * @param {string} column The column name. 
     80     * 
     81     * @returns {void} 
     82     */ 
    4383    checked : function(column) { 
    4484        $('.column-' + column).removeClass( 'hidden' ); 
     
    4686    }, 
    4787 
     88    /** 
     89     * @summary Hides a column and adjusts the column span for the table. 
     90     * 
     91     * @since 3.0.0 
     92     * @param {string} column The column name. 
     93     * 
     94     * @returns {void} 
     95     */ 
    4896    unchecked : function(column) { 
    4997        $('.column-' + column).addClass( 'hidden' ); 
     
    5199    }, 
    52100 
     101    /** 
     102     * @summary Get all hidden columns. 
     103     * 
     104     * @since 3.0.0 
     105     * 
     106     * @returns {string} The hidden column names separated by a comma. 
     107     */ 
    53108    hidden : function() { 
    54109        return $( '.manage-column[id]' ).filter( ':hidden' ).map(function() { 
     
    57112    }, 
    58113 
     114    /** 
     115     * @summary Gets the checked column toggles from the screen options. 
     116     * 
     117     * @since 3.0.0 
     118     * 
     119     * @returns {string} String containing the checked column names. 
     120     */ 
    59121    useCheckboxesForHidden : function() { 
    60122        this.hidden = function(){ 
     
    66128    }, 
    67129 
     130    /** 
     131     * @summary Adjusts the column span for the table. 
     132     * 
     133     * @since 3.1.0 
     134     * 
     135     * @param {int} diff The modifier for the column span. 
     136     */ 
    68137    colSpanChange : function(diff) { 
    69138        var $t = $('table').find('.colspanchange'), n; 
     
    77146$document.ready(function(){columns.init();}); 
    78147 
     148/** 
     149 * @summary Validates that the required form fields are not empty. 
     150 * 
     151 * @since 2.9.0 
     152 * 
     153 * @param {jQuery} form The form to validate. 
     154 * 
     155 * @returns {boolean} Returns true if all required fields are not an empty string. 
     156 */ 
    79157validateForm = function( form ) { 
    80158    return !$( form ) 
     
    88166 
    89167// stub for doing better warnings 
     168/** 
     169 * @summary Shows message pop-up notice or confirmation message. 
     170 * 
     171 * @since 2.7.0 
     172 * 
     173 * @type {{warn: showNotice.warn, note: showNotice.note}} 
     174 * 
     175 * @returns {void} 
     176 */ 
    90177showNotice = { 
     178 
     179    /** 
     180     * @summary Shows a delete confirmation pop-up message. 
     181     * 
     182     * @since 2.7.0 
     183     * 
     184     * @returns {boolean} Returns true if the message is confirmed. 
     185     */ 
    91186    warn : function() { 
    92187        var msg = commonL10n.warnDelete || ''; 
     
    98193    }, 
    99194 
     195    /** 
     196     * @summary Shows an alert message. 
     197     * 
     198     * @since 2.7.0 
     199     * 
     200     * @param text The text to display in the message. 
     201     */ 
    100202    note : function(text) { 
    101203        alert(text); 
     
    103205}; 
    104206 
     207/** 
     208 * @summary Represents the functions for the meta screen options panel. 
     209 * 
     210 * @since 3.2.0 
     211 * 
     212 * @type {{element: null, toggles: null, page: null, init: screenMeta.init, 
     213 *         toggleEvent: screenMeta.toggleEvent, open: screenMeta.open, 
     214 *         close: screenMeta.close}} 
     215 * 
     216 * @returns {void} 
     217 */ 
    105218screenMeta = { 
    106219    element: null, // #screen-meta 
     
    108221    page:    null, // #wpcontent 
    109222 
     223    /** 
     224     * @summary Initializes the screen meta options panel. 
     225     * 
     226     * @since 3.2.0 
     227     * 
     228     * @returns {void} 
     229     */ 
    110230    init: function() { 
    111231        this.element = $('#screen-meta'); 
     
    116236    }, 
    117237 
     238    /** 
     239     * @summary Toggles the screen meta options panel. 
     240     * 
     241     * @since 3.2.0 
     242     * 
     243     * @returns {void} 
     244     */ 
    118245    toggleEvent: function() { 
    119246        var panel = $( '#' + $( this ).attr( 'aria-controls' ) ); 
     
    128255    }, 
    129256 
     257    /** 
     258     * @summary Opens the screen meta options panel. 
     259     * 
     260     * @since 3.2.0 
     261     * 
     262     * @param {jQuery} panel  The screen meta options panel div. 
     263     * @param {jQuery} button The toggle button. 
     264     * 
     265     * @returns {void} 
     266     */ 
    130267    open: function( panel, button ) { 
    131268 
     
    133270 
    134271        panel.parent().show(); 
     272 
     273        /** 
     274         * @summary Sets the focus to the meta options panel and adds the necessary CSS classes. 
     275         * 
     276         * @since 3.2.0 
     277         * 
     278         * @returns {void} 
     279         */ 
    135280        panel.slideDown( 'fast', function() { 
    136281            panel.focus(); 
     
    141286    }, 
    142287 
     288    /** 
     289     * @summary Closes the screen meta options panel. 
     290     * 
     291     * @since 3.2.0 
     292     * 
     293     * @param {jQuery} panel  The screen meta options panel div. 
     294     * @param {jQuery} button The toggle button. 
     295     * 
     296     * @returns {void} 
     297     */ 
    143298    close: function( panel, button ) { 
     299        /** 
     300         * @summary Hides the screen meta options panel. 
     301         * 
     302         * @since 3.2.0 
     303         * 
     304         * @returns {void} 
     305         */ 
    144306        panel.slideUp( 'fast', function() { 
    145307            button.removeClass( 'screen-meta-active' ).attr( 'aria-expanded', false ); 
     
    153315 
    154316/** 
    155  * Help tabs. 
     317 * @summary Initializes the help tabs in the help panel. 
     318 * 
     319 * @param {Event} e The event object. 
     320 * 
     321 * @returns {void} 
    156322 */ 
    157323$('.contextual-help-tabs').delegate('a', 'click', function(e) { 
     
    179345 * Update custom permalink structure via buttons. 
    180346 */ 
    181  
    182347var permalinkStructureFocused = false, 
    183348    $permalinkStructure       = $( '#permalink_structure' ), 
     
    330495        $headerEnd = $( '.wp-header-end' ); 
    331496 
    332  
    333     // when the menu is folded, make the fly-out submenu header clickable 
     497    /** 
     498     * @summary Makes the fly-out submenu header clickable, when the menu is folded. 
     499     * 
     500     * @param {Event} e The event object. 
     501     * 
     502     * @returns {void} 
     503     */ 
    334504    $adminmenu.on('click.wp-submenu-head', '.wp-submenu-head', function(e){ 
    335505        $(e.target).parent().siblings('a').get(0).click(); 
    336506    }); 
    337507 
     508    /** 
     509     * @summary Collapses the admin menu. 
     510     * 
     511     * @returns {void} 
     512     */ 
    338513    $( '#collapse-button' ).on( 'click.collapse-menu', function() { 
    339514        var viewportWidth = getViewportWidth() || 961; 
     
    368543    }); 
    369544 
    370     // Handle the `aria-haspopup` attribute on the current menu item when it has a sub-menu. 
     545    /** 
     546     * @summary Handles the `aria-haspopup` attribute on the current menu item when it has a submenu. 
     547     * 
     548     * @since 4.4.0 
     549     * 
     550     * @returns {void} 
     551     */ 
    371552    function currentMenuItemHasPopup() { 
    372553        var $current = $( 'a.wp-has-current-submenu' ); 
     
    384565 
    385566    /** 
    386      * Ensure an admin submenu is within the visual viewport. 
     567     * @summary Ensures an admin submenu is within the visual viewport. 
    387568     * 
    388569     * @since 4.1.0 
    389570     * 
    390571     * @param {jQuery} $menuItem The parent menu item containing the submenu. 
     572     * 
     573     * @returns {void} 
    391574     */ 
    392575    function adjustSubmenu( $menuItem ) { 
     
    422605        mobileEvent = isIOS ? 'touchstart' : 'click'; 
    423606 
    424         // close any open submenus when touch/click is not on the menu 
     607        /** 
     608         * @summary Closes any open submenus when touch/click is not on the menu. 
     609         * 
     610         * @param {Event} e The event object. 
     611         * 
     612         * @returns {void} 
     613         */ 
    425614        $body.on( mobileEvent+'.wp-mobile-hover', function(e) { 
    426615            if ( $adminmenu.data('wp-responsive') ) { 
     
    433622        }); 
    434623 
     624        /** 
     625         * @summary Handles the opening or closing the submenu based on the mobile click|touch event. 
     626         * 
     627         * @param {Event} event The event object. 
     628         * 
     629         * @returns {void} 
     630         */ 
    435631        $adminmenu.find( 'a.wp-has-submenu' ).on( mobileEvent + '.wp-mobile-hover', function( event ) { 
    436632            var $menuItem = $(this).parent(); 
     
    454650    if ( ! isIOS && ! isAndroid ) { 
    455651        $adminmenu.find( 'li.wp-has-submenu' ).hoverIntent({ 
     652 
     653            /** 
     654             * @summary Opens the submenu when hovered over the menu item for desktops. 
     655             * 
     656             * @returns {void} 
     657             */ 
    456658            over: function() { 
    457659                var $menuItem = $( this ), 
     
    472674                $menuItem.addClass( 'opensub' ); 
    473675            }, 
     676 
     677            /** 
     678             * @summary Closes the submenu when no longer hovering the menu item. 
     679             * 
     680             * @returns {void} 
     681             */ 
    474682            out: function(){ 
    475683                if ( $adminmenu.data( 'wp-responsive' ) ) { 
     
    485693        }); 
    486694 
     695        /** 
     696         * @summary Opens the submenu on when focused on the menu item. 
     697         * 
     698         * @param {Event} event The event object. 
     699         * 
     700         * @returns {void} 
     701         */ 
    487702        $adminmenu.on( 'focus.adminmenu', '.wp-submenu a', function( event ) { 
    488703            if ( $adminmenu.data( 'wp-responsive' ) ) { 
     
    492707 
    493708            $( event.target ).closest( 'li.menu-top' ).addClass( 'opensub' ); 
     709 
     710            /** 
     711             * @summary Closes the submenu on blur from the menu item. 
     712             * 
     713             * @param {Event} event The event object. 
     714             * 
     715             * @returns {void} 
     716             */ 
    494717        }).on( 'blur.adminmenu', '.wp-submenu a', function( event ) { 
    495718            if ( $adminmenu.data( 'wp-responsive' ) ) { 
     
    498721 
    499722            $( event.target ).closest( 'li.menu-top' ).removeClass( 'opensub' ); 
     723 
     724            /** 
     725             * @summary Adjusts the size for the submenu. 
     726             * 
     727             * @returns {void} 
     728             */ 
    500729        }).find( 'li.wp-has-submenu.wp-not-current-submenu' ).on( 'focusin.adminmenu', function() { 
    501730            adjustSubmenu( $( this ) ); 
     
    514743    $( 'div.updated, div.error, div.notice' ).not( '.inline, .below-h2' ).insertAfter( $headerEnd ); 
    515744 
    516     // Make notices dismissible 
     745    /** 
     746     * @summary Make notices dismissible. 
     747     * 
     748     * @since 4.4.0 
     749     * 
     750     * @returns {void} 
     751     */ 
    517752    function makeNoticesDismissible() { 
    518753        $( '.notice.is-dismissible' ).each( function() { 
     
    541776    screenMeta.init(); 
    542777 
    543     // This event needs to be delegated. Ticket #37973. 
     778    /** 
     779     * @summary Checks a checkbox. 
     780     * 
     781     * This event needs to be delegated. Ticket #37973. 
     782     * 
     783     * @returns {boolean} Returns whether a checkbox is checked or not. 
     784     */ 
    544785    $body.on( 'click', 'tbody > tr > .check-column :checkbox', function( event ) { 
    545786        // Shift click to select a range of checkboxes. 
     
    565806        // Toggle the "Select all" checkboxes depending if the other ones are all checked or not. 
    566807        var unchecked = $(this).closest('tbody').find(':checkbox').filter(':visible:enabled').not(':checked'); 
     808 
     809        /** 
     810         * @summary Determines if all checkboxes are checked. 
     811         * 
     812         * @returns {boolean} Returns true if there are no unchecked checkboxes. 
     813         */ 
    567814        $(this).closest('table').children('thead, tfoot').find(':checkbox').prop('checked', function() { 
    568815            return ( 0 === unchecked.length ); 
     
    572819    }); 
    573820 
    574     // This event needs to be delegated. Ticket #37973. 
     821    /** 
     822     * @summary Controls all the toggles on bulk toggle change. 
     823     * 
     824     * When the bulk checkbox is changed, all the checkboxes in the tables are changed accordingly. 
     825     * When the shift-button is pressed while changing the bulk checkbox the checkboxes in the table are inverted. 
     826     * 
     827     * This event needs to be delegated. Ticket #37973. 
     828     * 
     829     * @param {Event} event The event object. 
     830     * 
     831     * @returns {boolean} 
     832     */ 
    575833    $body.on( 'click.wp-toggle-checkboxes', 'thead .check-column :checkbox, tfoot .check-column :checkbox', function( event ) { 
    576834        var $this = $(this), 
     
    581839        $table.children( 'tbody' ).filter(':visible') 
    582840            .children().children('.check-column').find(':checkbox') 
     841            /** 
     842             * @summary Updates the checked state on the checkbox in the table. 
     843             * 
     844             * @returns {boolean} True checks the checkbox, False unchecks the checkbox. 
     845             */ 
    583846            .prop('checked', function() { 
    584847                if ( $(this).is(':hidden,:disabled') ) { 
     
    597860        $table.children('thead,  tfoot').filter(':visible') 
    598861            .children().children('.check-column').find(':checkbox') 
     862 
     863            /** 
     864             * @summary Syncs the bulk checkboxes on the top and bottom of the table. 
     865             * 
     866             * @returns {boolean} True checks the checkbox, False unchecks the checkbox. 
     867             */ 
    599868            .prop('checked', function() { 
    600869                if ( toggle ) { 
     
    608877    }); 
    609878 
    610     // Show row actions on keyboard focus of its parent container element or any other elements contained within 
     879    /** 
     880     * @summary Shows row actions on focus of its parent container element or any other elements contained within. 
     881     * 
     882     * @returns {void} 
     883     */ 
    611884    $( '#wpbody-content' ).on({ 
    612885        focusin: function() { 
     
    637910    }); 
    638911 
    639     // tab in textareas 
     912    /** 
     913     * @summary Handles tab keypresses in theme and plugin editor textareas. 
     914     * 
     915     * @param {Event} e The event object. 
     916     * 
     917     * @returns {void} 
     918     */ 
    640919    $('#newcontent').bind('keydown.wpevent_InsertTab', function(e) { 
    641920        var el = e.target, selStart, selEnd, val, scroll, sel; 
    642921 
    643         if ( e.keyCode == 27 ) { // escape key 
     922        // After pressing escape key (keyCode: 27), the tab key should tab out of the textarea. 
     923        if ( e.keyCode == 27 ) { 
    644924            // when pressing Escape: Opera 12 and 27 blur form fields, IE 8 clears them 
    645925            e.preventDefault(); 
     
    648928        } 
    649929 
    650         if ( e.keyCode != 9 || e.ctrlKey || e.altKey || e.shiftKey ) // tab key 
     930        // Only listen for plain tab key (keyCode: 9) without any modifiers. 
     931        if ( e.keyCode != 9 || e.ctrlKey || e.altKey || e.shiftKey ) 
    651932            return; 
    652933 
     934        // After tabbing out, reset it so next time the tab key can be used again. 
    653935        if ( $(el).data('tab-out') ) { 
    654936            $(el).data('tab-out', false); 
     
    660942        val = el.value; 
    661943 
     944        // If any text is selected, replace the selection with a tab character. 
    662945        if ( document.selection ) { 
    663946            el.focus(); 
     
    671954        } 
    672955 
     956        // Cancel the regular tab functionality, to prevent losing focus of the textarea. 
    673957        if ( e.stopPropagation ) 
    674958            e.stopPropagation(); 
     
    677961    }); 
    678962 
     963    // Reset page number variable for new filters/searches but not for bulk actions. See #17685. 
    679964    if ( pageInput.length ) { 
     965 
     966        /** 
     967         * @summary Handles pagination variable when filtering the list table. 
     968         * 
     969         * Set the pagination argument to the first page when the post-filter form is submitted. 
     970         * This happens when pressing the 'filter' button on the list table page. 
     971         * 
     972         * The pagination argument should not be touched when the bulk action dropdowns are set to do anything. 
     973         * 
     974         * The form closest to the pageInput is the post-filter form. 
     975         * 
     976         * @returns {void} 
     977         */ 
    680978        pageInput.closest('form').submit( function() { 
    681  
    682             // Reset paging var for new filters/searches but not for bulk actions. See #17685. 
     979            /* 
     980             * action = bulk action dropdown at the top of the table 
     981             * action2 = bulk action dropdow at the bottom of the table 
     982             */ 
    683983            if ( $('select[name="action"]').val() == -1 && $('select[name="action2"]').val() == -1 && pageInput.val() == currentPage ) 
    684984                pageInput.val('1'); 
     
    686986    } 
    687987 
     988    /** 
     989     * @summary Resets the bulk actions when the search button is clicked. 
     990     * 
     991     * @returns {void} 
     992     */ 
    688993    $('.search-box input[type="search"], .search-box input[type="submit"]').mousedown(function () { 
    689994        $('select[name^="action"]').val('-1'); 
    690995    }); 
    691996 
    692     // Scroll into view when focused 
     997    /** 
     998     * @summary Scrolls into view when focus.scroll-into-view is triggered. 
     999     * 
     1000     * @param {Event} e The event object. 
     1001     * 
     1002     * @returns {void} 
     1003     */ 
    6931004    $('#contextual-help-link, #show-settings-link').on( 'focus.scroll-into-view', function(e){ 
    6941005        if ( e.target.scrollIntoView ) 
     
    6961007    }); 
    6971008 
    698     // Disable upload buttons until files are selected 
     1009    /** 
     1010     * @summary Disables the submit upload buttons when no data is entered. 
     1011     * 
     1012     * @returns {void} 
     1013     */ 
    6991014    (function(){ 
    7001015        var button, input, form = $('form.wp-upload-form'); 
     1016 
     1017        // Exit when no upload form is found. 
    7011018        if ( ! form.length ) 
    7021019            return; 
     1020 
    7031021        button = form.find('input[type="submit"]'); 
    7041022        input = form.find('input[type="file"]'); 
    7051023 
     1024        /** 
     1025         * @summary Determines if any data is entered in any file upload input. 
     1026         * 
     1027         * @since 3.5.0 
     1028         * 
     1029         * @returns {void} 
     1030         */ 
    7061031        function toggleUploadButton() { 
     1032            // When no inputs have a value, disable the upload buttons. 
    7071033            button.prop('disabled', '' === input.map( function() { 
    7081034                return $(this).val(); 
    7091035            }).get().join('')); 
    7101036        } 
     1037 
     1038        // Update the status initially. 
    7111039        toggleUploadButton(); 
     1040        // Update the status when any file input changes. 
    7121041        input.on('change', toggleUploadButton); 
    7131042    })(); 
    7141043 
     1044    /** 
     1045     * @summary Pins the menu while distraction-free writing is enabled. 
     1046     * 
     1047     * @param {Event} event Event data. 
     1048     * 
     1049     * @since 4.1.0 
     1050     * 
     1051     * @returns {void} 
     1052     */ 
    7151053    function pinMenu( event ) { 
    7161054        var windowPos = $window.scrollTop(), 
     
    7211059        } 
    7221060 
     1061        /* 
     1062         * When the menu is higher than the window and smaller than the entire page. 
     1063         * It should be adjusted to be able to see the entire menu. 
     1064         * 
     1065         * Otherwise it can be accessed normally. 
     1066         */ 
    7231067        if ( height.menu + height.adminbar < height.window || 
    7241068            height.menu + height.adminbar + 20 > height.wpwrap ) { 
     
    7291073        menuIsPinned = true; 
    7301074 
     1075        // If the menu is higher than the window, compensate on scroll. 
    7311076        if ( height.menu + height.adminbar > height.window ) { 
    732             // Check for overscrolling 
     1077            // Check for overscrolling, this happens when swiping up at the top of the document in modern browsers. 
    7331078            if ( windowPos < 0 ) { 
     1079                // Stick the menu to the top. 
    7341080                if ( ! pinnedMenuTop ) { 
    7351081                    pinnedMenuTop = true; 
     
    7451091                return; 
    7461092            } else if ( windowPos + height.window > $document.height() - 1 ) { 
     1093                // When overscrolling at the bottom, stick the menu to the bottom. 
    7471094                if ( ! pinnedMenuBottom ) { 
    7481095                    pinnedMenuBottom = true; 
     
    7601107 
    7611108            if ( windowPos > lastScrollPosition ) { 
    762                 // Scrolling down 
     1109                // When a down scroll has been detected. 
     1110 
     1111                // If it was pinned to the top, unpin and calculate relative scroll. 
    7631112                if ( pinnedMenuTop ) { 
    764                     // let it scroll 
    7651113                    pinnedMenuTop = false; 
     1114                    // Calculate new offset position. 
    7661115                    menuTop = $adminMenuWrap.offset().top - height.adminbar - ( windowPos - lastScrollPosition ); 
    7671116 
     
    7761125                    }); 
    7771126                } else if ( ! pinnedMenuBottom && $adminMenuWrap.offset().top + height.menu < windowPos + height.window ) { 
    778                     // pin the bottom 
     1127                    // Pin it to the bottom. 
    7791128                    pinnedMenuBottom = true; 
    7801129 
     
    7861135                } 
    7871136            } else if ( windowPos < lastScrollPosition ) { 
    788                 // Scrolling up 
     1137                // When a scroll up is detected. 
     1138 
     1139                // If it was pinned to the bottom, unpin and calculate relative scroll. 
    7891140                if ( pinnedMenuBottom ) { 
    790                     // let it scroll 
    7911141                    pinnedMenuBottom = false; 
     1142 
     1143                    // Calculate new offset position. 
    7921144                    menuTop = $adminMenuWrap.offset().top - height.adminbar + ( lastScrollPosition - windowPos ); 
    7931145 
     
    8021154                    }); 
    8031155                } else if ( ! pinnedMenuTop && $adminMenuWrap.offset().top >= windowPos + height.adminbar ) { 
    804                     // pin the top 
     1156 
     1157                    // Pin it to the top. 
    8051158                    pinnedMenuTop = true; 
    8061159 
     
    8121165                } 
    8131166            } else if ( resizing ) { 
    814                 // Resizing 
     1167                // Window is being resized. 
     1168 
    8151169                pinnedMenuTop = pinnedMenuBottom = false; 
     1170 
     1171                // Calculate the new offset. 
    8161172                menuTop = windowPos + height.window - height.menu - height.adminbar - 1; 
    8171173 
     
    8311187    } 
    8321188 
     1189    /** 
     1190     * @summary Determines the height of certain elements. 
     1191     * 
     1192     * @since 4.1.0 
     1193     * 
     1194     * @returns {void} 
     1195     */ 
    8331196    function resetHeights() { 
    8341197        height = { 
     
    8401203    } 
    8411204 
     1205    /** 
     1206     * @summary Unpins the menu. 
     1207     * 
     1208     * @since 4.1.0 
     1209     * 
     1210     * @returns {void} 
     1211     */ 
    8421212    function unpinMenu() { 
    8431213        if ( isIOS || ! menuIsPinned ) { 
     
    8531223    } 
    8541224 
     1225    /** 
     1226     * @summary Pins and unpins the menu when applicable. 
     1227     * 
     1228     * @since 4.1.0 
     1229     * 
     1230     * @returns {void} 
     1231     */ 
    8551232    function setPinMenu() { 
    8561233        resetHeights(); 
     
    8751252    } 
    8761253 
     1254    /** 
     1255     * @summary Changes properties of metaboxes and body. 
     1256     * 
     1257     * Changes the sortables and responsiveness of metaboxes. 
     1258     * 
     1259     * @since 3.8.0 
     1260     * 
     1261     *@returns {void} 
     1262     */ 
    8771263    window.wpResponsive = { 
     1264 
     1265        /** 
     1266         * @summary Initializes the wpResponsive object. 
     1267         * 
     1268         * @since 3.8.0 
     1269         * 
     1270         * @returns {void} 
     1271         */ 
    8781272        init: function() { 
    8791273            var self = this; 
     
    8881282            $( '#wp-admin-bar-menu-toggle a' ).attr( 'aria-expanded', 'false' ); 
    8891283 
    890             // Toggle sidebar when toggle is clicked 
     1284            // Toggle sidebar when toggle is clicked. 
    8911285            $( '#wp-admin-bar-menu-toggle' ).on( 'click.wp-responsive', function( event ) { 
    8921286                event.preventDefault(); 
    8931287 
    894                 // close any open toolbar submenus 
     1288                // close any open toolbar submenus. 
    8951289                $adminbar.find( '.hover' ).removeClass( 'hover' ); 
    8961290 
     
    9041298            } ); 
    9051299 
    906             // Add menu events 
     1300            // Add menu events. 
    9071301            $adminmenu.on( 'click.wp-responsive', 'li.wp-has-submenu > a', function( event ) { 
    9081302                if ( ! $adminmenu.data('wp-responsive') ) { 
     
    9171311            $document.on( 'wp-window-resized.wp-responsive', $.proxy( this.trigger, this ) ); 
    9181312 
    919             // This needs to run later as UI Sortable may be initialized later on $(document).ready() 
     1313            // This needs to run later as UI Sortable may be initialized later on $(document).ready(). 
    9201314            $window.on( 'load.wp-responsive', function() { 
    9211315                var width = navigator.userAgent.indexOf('AppleWebKit/') > -1 ? $window.width() : window.innerWidth; 
     
    9271321        }, 
    9281322 
     1323        /** 
     1324         * @summary Changes properties of body and admin menu. 
     1325         * 
     1326         * Pins and unpins the menu and adds the auto-fold class to the body. 
     1327         * Makes the admin menu responsive and disables the metabox sortables. 
     1328         * 
     1329         * @since 3.8.0 
     1330         * 
     1331         * @returns {void} 
     1332         */ 
    9291333        activate: function() { 
    9301334            setPinMenu(); 
    9311335 
    932             if ( ! $body.hasClass( 'auto-fold' ) ) { 
    933                 $body.addClass( 'auto-fold' ); 
    934             } 
    935  
    936             $adminmenu.data( 'wp-responsive', 1 ); 
     1336            if ( ! $body.hasClass( "auto-fold" ) ) { 
     1337                $body.addClass( "auto-fold" ); 
     1338            } 
     1339 
     1340            $adminmenu.data( "wp-responsive", 1 ); 
    9371341            this.disableSortables(); 
    9381342        }, 
    9391343 
     1344        /** 
     1345         * @summary Changes properties of admin menu and enables metabox sortables. 
     1346         * 
     1347         * Pin and unpin the menu. 
     1348         * Removes the responsiveness of the admin menu and enables the metabox sortables. 
     1349         * 
     1350         * @since 3.8.0 
     1351         * 
     1352         * @returns {void} 
     1353         */ 
    9401354        deactivate: function() { 
    9411355            setPinMenu(); 
     
    9441358        }, 
    9451359 
     1360        /** 
     1361         * @summary Sets the responsiveness and enables the overlay based on the viewport width. 
     1362         * 
     1363         * @since 3.8.0 
     1364         * 
     1365         * @returns {void} 
     1366         */ 
    9461367        trigger: function() { 
    9471368            var viewportWidth = getViewportWidth(); 
     
    9541375            if ( viewportWidth <= 782 ) { 
    9551376                if ( ! wpResponsiveActive ) { 
    956                     $document.trigger( 'wp-responsive-activate' ); 
     1377                    $document.trigger( "wp-responsive-activate" ); 
    9571378                    wpResponsiveActive = true; 
    9581379                } 
    9591380            } else { 
    9601381                if ( wpResponsiveActive ) { 
    961                     $document.trigger( 'wp-responsive-deactivate' ); 
     1382                    $document.trigger( "wp-responsive-deactivate" ); 
    9621383                    wpResponsiveActive = false; 
    9631384                } 
     
    9711392        }, 
    9721393 
     1394        /** 
     1395         * @summary Inserts a responsive overlay and toggles the window. 
     1396         * 
     1397         * @since 3.8.0 
     1398         * 
     1399         * @returns {void} 
     1400         */ 
    9731401        enableOverlay: function() { 
    9741402            if ( $overlay.length === 0 ) { 
     
    9871415        }, 
    9881416 
     1417        /** 
     1418         * @summary Disables the responsive overlay and removes the overlay. 
     1419         * 
     1420         * @since 3.8.0 
     1421         * 
     1422         * @returns {void} 
     1423         */ 
    9891424        disableOverlay: function() { 
    990             $toolbarPopups.off( 'click.wp-responsive' ); 
     1425            $toolbarPopups.off( "click.wp-responsive" ); 
    9911426            $overlay.hide(); 
    9921427        }, 
    9931428 
     1429        /** 
     1430         * @summary Disables sortables. 
     1431         * 
     1432         * @since 3.8.0 
     1433         * 
     1434         * @returns {void} 
     1435         */ 
    9941436        disableSortables: function() { 
    9951437            if ( $sortables.length ) { 
    9961438                try { 
    997                     $sortables.sortable('disable'); 
    998                 } catch(e) {} 
     1439                    $sortables.sortable( "disable" ); 
     1440                } catch ( e ) {} 
    9991441            } 
    10001442        }, 
    10011443 
     1444        /** 
     1445         * @summary Enables sortables. 
     1446         * 
     1447         * @since 3.8.0 
     1448         * 
     1449         * @returns {void} 
     1450         */ 
    10021451        enableSortables: function() { 
    10031452            if ( $sortables.length ) { 
    10041453                try { 
    1005                     $sortables.sortable('enable'); 
    1006                 } catch(e) {} 
     1454                    $sortables.sortable( "enable" ); 
     1455                } catch ( e ) {} 
    10071456            } 
    10081457        } 
    10091458    }; 
    10101459 
    1011     // Add an ARIA role `button` to elements that behave like UI controls when JavaScript is on. 
     1460    /** 
     1461     * @summary Add an ARIA role `button` to elements that behave like UI controls when JavaScript is on. 
     1462     * 
     1463     * @since 4.5.0 
     1464     * 
     1465     * @returns {void} 
     1466     */ 
    10121467    function aria_button_if_js() { 
    1013         $( '.aria-button-if-js' ).attr( 'role', 'button' ); 
     1468        $( ".aria-button-if-js" ).attr( "role", "button" ); 
    10141469    } 
    10151470 
     
    10381493 
    10391494    /** 
    1040      * @summary Set the admin menu collapsed/expanded state. 
     1495     * @summary Sets the admin menu collapsed/expanded state. 
    10411496     * 
    10421497     * Sets the global variable `menuState` and triggers a custom event passing 
     
    10651520 
    10661521    /** 
    1067      * @summary Set ARIA attributes on the collapse/expand menu button. 
     1522     * @summary Sets ARIA attributes on the collapse/expand menu button. 
    10681523     * 
    10691524     * When the admin menu is open or folded, updates the `aria-expanded` and 
     
    11231578}); 
    11241579 
    1125 // Fire a custom jQuery event at the end of window resize 
     1580// Fire a custom jQuery event at the end of window resize. 
    11261581( function() { 
    11271582    var timeout; 
    11281583 
     1584    /** 
     1585     * @summary Triggers the WP window-resize event. 
     1586     * 
     1587     * @since 3.8.0 
     1588     * 
     1589     * @returns {void} 
     1590     */ 
    11291591    function triggerEvent() { 
    1130         $document.trigger( 'wp-window-resized' ); 
    1131     } 
    1132  
     1592        $document.trigger( "wp-window-resized" ); 
     1593    } 
     1594 
     1595    /** 
     1596     * @summary Fires the trigger event again after 200 ms. 
     1597     * 
     1598     * @since 3.8.0 
     1599     * 
     1600     * @returns {void} 
     1601     */ 
    11331602    function fireOnce() { 
    11341603        window.clearTimeout( timeout ); 
Note: See TracChangeset for help on using the changeset viewer.