WordPress.org
Get WordPress

Make WordPress Core

Changeset 42351


Ignore:
Timestamp:
12/03/2017 06:10:21 PM (7 years 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.