Changeset 43355

Timestamp:

06/16/2018 10:28:56 AM (6 years ago)

Author:

atimmer

Message:

Docs: Improve JSDoc for auth-check.js.

Props pskli.
Fixes #44364.

File:

• trunk/src/js/_enqueues/lib/auth-check.js (modified) (7 diffs)

trunk/src/js/_enqueues/lib/auth-check.js

@@ -9 +9 @@
     var wrap, next;
 
+    /**
+     * Shows the authentication form popup.
+     *
+     * @since 3.6.0
+     * @private
+     */
     function show() {
         var parent = $('#wp-auth-check'),
@@ -16 +22 @@
 
         if ( form.length ) {
-            // Add unload confirmation to counter (frame-busting) JS redirects
+            // Add unload confirmation to counter (frame-busting) JS redirects.
             $(window).on( 'beforeunload.wp-auth-check', function(e) {
                 e.originalEvent.returnValue = window.authcheckL10n.beforeunload;
@@ -46 +52 @@
                         parent.css( 'max-height', height + 40 + 'px' );
                 } else if ( ! body || ! body.length ) {
-                    // Catch "silent" iframe origin exceptions in WebKit after another page is loaded in the iframe
+                    // Catch "silent" iframe origin exceptions in WebKit after another page is
+                    // loaded in the iframe.
                     wrap.addClass('fallback');
                     parent.css( 'max-height', '' );
@@ -62 +69 @@
         if ( frame ) {
             frame.focus();
-            // WebKit doesn't throw an error if the iframe fails to load because of "X-Frame-Options: DENY" header.
+            // WebKit doesn't throw an error if the iframe fails to load because of
+            // "X-Frame-Options: DENY" header.
             // Wait for 10 sec. and switch to the fallback text.
             setTimeout( function() {
@@ -76 +84 @@
     }
 
+    /**
+     * Hides the authentication form popup.
+     *
+     * @since 3.6.0
+     * @private
+     */
     function hide() {
         $(window).off( 'beforeunload.wp-auth-check' );
 
-        // When on the Edit Post screen, speed up heartbeat after the user logs in to quickly refresh nonces
+        // When on the Edit Post screen, speed up heartbeat after the user logs in to
+        // quickly refresh nonces.
         if ( typeof adminpage !== 'undefined' && ( adminpage === 'post-php' || adminpage === 'post-new-php' ) &&
             typeof wp !== 'undefined' && wp.heartbeat ) {
@@ -94 +109 @@
     }
 
+    /**
+     * Schedules when the next time the authentication check will be done.
+     *
+     * @since 3.6.0
+     * @private
+     */
     function schedule() {
-        var interval = parseInt( window.authcheckL10n.interval, 10 ) || 180; // in seconds, default 3 min.
+        // In seconds, default 3 min.
+        var interval = parseInt( window.authcheckL10n.interval, 10 ) || 180;
         next = ( new Date() ).getTime() + ( interval * 1000 );
     }
 
+    /**
+     * Binds to the Heartbeat Tick event.
+     *
+     * - Shows the authentication form popup if user is not logged in.
+     * - Hides the authentication form popup if it is already visible and user is
+     *   logged in.
+     *
+     * @ignore
+     *
+     * @since 3.6.0
+     *
+     * @param {Object} e The heartbeat-tick event that has been triggered.
+     * @param {Object} data Response data.
+     */
     $( document ).on( 'heartbeat-tick.wp-auth-check', function( e, data ) {
         if ( 'wp-auth-check' in data ) {
@@ -108 +144 @@
             }
         }
+
+    /**
+     * Binds to the Heartbeat Send event.
+     *
+     * @ignore
+     *
+     * @since 3.6.0
+     *
+     * @param {Object} e The heartbeat-send event that has been triggered.
+     * @param {Object} data Response data.
+     */
     }).on( 'heartbeat-send.wp-auth-check', function( e, data ) {
         if ( ( new Date() ).getTime() > next ) {
             data['wp-auth-check'] = true;
         }
+
     }).ready( function() {
         schedule();
+
+        /**
+         * Hides the authentication form popup when the close icon is clicked.
+         *
+         * @ignore
+         *
+         * @since 3.6.0
+         */
         wrap = $('#wp-auth-check-wrap');
         wrap.find('.wp-auth-check-close').on( 'click', function() {