Ticket #41203: autosave.diff

src/wp-includes/js/autosave.js

@@ -4 +4 @@
         return true;
 };
 
+/**
+ * @summary Adds autosave to the window object on dom ready.
+ *
+ * @since 3.9.0
+ *
+ * @param {jQuery} $ jQuery object.
+ * @param {window} The window object.
+ *
+ */
 ( function( $, window ) {
+        /**
+         * @summary Auto saves the post.
+         *
+         * @since 3.9.0
+         *
+         * @returns {Object}
+         *      {{
+         *              getPostData: getPostData,
+         *              getCompareString: getCompareString,
+         *              disableButtons: disableButtons,
+         *              enableButtons: enableButtons,
+         *              local: ({hasStorage, getSavedPostData, save, suspend, resume}|*),
+         *              server: ({tempBlockSave, triggerSave, postChanged, suspend, resume}|*)}
+         *      }
+         *      The object with all functions for autosave.
+         */
         function autosave() {
                 var initialCompareString,
                         lastTriggerSave = 0,
                         $document = $(document);
 
                 /**
-                 * Returns the data saved in both local and remote autosave
+                 * @summary Returns the data saved in both local and remote autosave.
                  *
-                 * @return object Object containing the post data
+                 * @since 3.9.0
+                 *
+                 * @param {string} type The type of autosave either local or remote.
+                 *
+                 * @returns {Object} Object containing the post data.
                  */
                 function getPostData( type ) {
                         var post_name, parent_id, data,
@@ -69 +98 @@
                         return data;
                 }
 
-                // Concatenate title, content and excerpt. Used to track changes when auto-saving.
+                /**
+                 * @summary Concatenates the title, content and excerpt.
+                 *
+                 * This is used to track changes when auto-saving.
+                 *
+                 * @since 3.9.0
+                 *
+                 * @param {Object} postData The object containing the post data.
+                 * @returns {string} A concatenated string with title, content and excerpt.
+                 */
                 function getCompareString( postData ) {
                         if ( typeof postData === 'object' ) {
                                 return ( postData.post_title || '' ) + '::' + ( postData.content || '' ) + '::' + ( postData.excerpt || '' );
@@ -78 +116 @@
                         return ( $('#title').val() || '' ) + '::' + ( $('#content').val() || '' ) + '::' + ( $('#excerpt').val() || '' );
                 }
 
+                /**
+                 * @summary Disables save buttons.
+                 *
+                 * @since 3.9.0
+                 *
+                 * @returns {void}
+                 */
                 function disableButtons() {
                         $document.trigger('autosave-disable-buttons');
                         // Re-enable 5 sec later. Just gives autosave a head start to avoid collisions.
                         setTimeout( enableButtons, 5000 );
                 }
 
+                /**
+                 * @summary Enables save buttons.
+                 *
+                 * @since 3.9.0
+                 *
+                 * @returns {void}
+                 */
                 function enableButtons() {
                         $document.trigger( 'autosave-enable-buttons' );
                 }
 
+                /**
+                 * @summary Gets the content editor.
+                 *
+                 * @since 4.6.0
+                 *
+                 * @returns {boolean|*} Returns either false if the editor is undefined,
+                 *                                              or the instance of the content editor.
+                 */
                 function getEditor() {
                         return typeof tinymce !== 'undefined' && tinymce.get('content');
                 }
 
-                // Autosave in localStorage
+                /**
+                 * @summary Autosaves in the localStorage.
+                 *
+                 * @since 3.9.0
+                 *
+                 * @returns {
+                 * {
+                 *      hasStorage: *,
+                 *      getSavedPostData: getSavedPostData,
+                 *      save: save,
+                 *      suspend: suspend,
+                 *      resume: resume
+                 *      }
+                 * }
+                 * The object with all functions for local storage autosave.
+                 */
                 function autosaveLocal() {
                         var blog_id, post_id, hasStorage, intervalTimer,
                                 lastCompareString,
                                 isSuspended = false;
 
-                        // Check if the browser supports sessionStorage and it's not disabled
+                        /**
+                         * @summary Checks if the browser supports sessionStorage and it's not disabled.
+                         *
+                         * @since 3.9.0
+                         *
+                         * @returns {boolean} True if the sessionStorage is supported and enabled.
+                         */
                         function checkStorage() {
                                 var test = Math.random().toString(),
                                         result = false;
@@ -114 +195 @@
                         }
 
                         /**
-                         * Initialize the local storage
+                         * @summary Initializes the local storage.
                          *
-                         * @return mixed False if no sessionStorage in the browser or an Object containing all postData for this blog
+                         * @since 3.9.0
+                         *
+                         * @returns {boolean|Object} False if no sessionStorage in the browser or an Object containing all postData for this blog.
                          */
                         function getStorage() {
                                 var stored_obj = false;
@@ -135 +218 @@
                         }
 
                         /**
-                         * Set the storage for this blog
+                         * @summary Sets the storage for this blog.
                          *
                          * Confirms that the data was saved successfully.
                          *
-                         * @return bool
+                         * @since 3.9.0
+                         *
+                         * @returns {boolean} True if the data was saved successfully, false if it wasn't saved.
                          */
                         function setStorage( stored_obj ) {
                                 var key;
@@ -154 +239 @@
                         }
 
                         /**
-                         * Get the saved post data for the current post
+                         * @summary Gets the saved post data for the current post.
                          *
-                         * @return mixed False if no storage or no data or the postData as an Object
+                         * @since 3.9.0
+                         *
+                         * @returns {boolean|Object} False if no storage or no data or the postData as an Object.
                          */
                         function getSavedPostData() {
                                 var stored = getStorage();
@@ -169 +256 @@
                         }
 
                         /**
-                         * Set (save or delete) post data in the storage.
+                         * @summary Sets (save or delete) post data in the storage.
+                         *
+                         * If stored_data evaluates to 'false' the storage key for the current post will be removed.
                          *
-                         * If stored_data evaluates to 'false' the storage key for the current post will be removed
+                         * @since 3.9.0
                          *
-                         * $param stored_data The post data to store or null/false/empty to delete the key
-                         * @return bool
+                         * @param {Object|boolean|null} stored_data The post data to store or null/false/empty to delete the key.
+                         *
+                         * @returns {boolean} True if data is stored, false if data was removed.
                          */
                         function setData( stored_data ) {
                                 var stored = getStorage();
@@ -194 +284 @@
                                 return setStorage( stored );
                         }
 
+                        /**
+                         * @summary Sets isSuspended to true.
+                         *
+                         * @since 3.9.0
+                         *
+                         * @returns {void}
+                         */
                         function suspend() {
                                 isSuspended = true;
                         }
 
+                        /**
+                         * @summary Sets isSuspended to false.
+                         *
+                         * @since 3.9.0
+                         *
+                         * @returns {void}
+                         */
                         function resume() {
                                 isSuspended = false;
                         }
 
                         /**
-                         * Save post data for the current post
+                         * @summary Saves post data for the current post.
                          *
                          * Runs on a 15 sec. interval, saves when there are differences in the post title or content.
                          * When the optional data is provided, updates the last saved post data.
                          *
-                         * $param data optional Object The post data for saving, minimum 'post_title' and 'content'
-                         * @return bool
+                         * @since 3.9.0
+                         *
+                         * @param {Object} data The post data for saving, minimum 'post_title' and 'content'.
+                         *
+                         * @returns {boolean} Returns true when data has been saved, otherwise it returns false.
                          */
                         function save( data ) {
                                 var postData, compareString,
@@ -248 +355 @@
                                 return result;
                         }
 
-                        // Run on DOM ready
+                        /**
+                         * @summary Initializes the auto save function.
+                         *
+                         * Checks whether the editor is active or not to use the editor events
+                         * to autosave, or uses the values from the elements to autosave.
+                         *
+                         * Runs on DOM ready.
+                         *
+                         * @since 3.9.0
+                         *
+                         * @returns {void}
+                         */
                         function run() {
                                 post_id = $('#post_ID').val() || 0;
 
@@ -295 +413 @@
                                 });
                         }
 
-                        // Strip whitespace and compare two strings
+                        /**
+                         * @summary Compares 2 strings.
+                         *
+                         * Removes whitespaces in the strings before comparing them.
+                         *
+                         * @since 3.9.0
+                         *
+                         * @param {string} str1 The first string.
+                         * @param {string} str2 The second string.
+                         * @returns {boolean} True if the strings are the same.
+                         */
                         function compare( str1, str2 ) {
                                 function removeSpaces( string ) {
                                         return string.toString().replace(/[\x20\t\r\n\f]+/g, '');
@@ -305 +433 @@
                         }
 
                         /**
-                         * Check if the saved data for the current post (if any) is different than the loaded post data on the screen
+                         * @summary Checks if the saved data for the current post (if any) is different
+                         * than the loaded post data on the screen.
                          *
                          * Shows a standard message letting the user restore the post data if different.
                          *
-                         * @return void
+                         * @since 3.9.0
+                         *
+                         * @returns {void}
                          */
                         function checkPost() {
                                 var content, post_title, excerpt, $notice,
@@ -369 +500 @@
                                 });
                         }
 
-                        // Restore the current title, content and excerpt from postData.
+                        /**
+                         * @summary Restores the current title, content and excerpt from postData.
+                         *
+                         * @since 3.9.0
+                         *
+                         * @param {Object} postData The object containing all post data.
+                         * @returns {boolean} True if the post is restored.
+                         */
                         function restorePost( postData ) {
                                 var editor;
 
@@ -427 +565 @@
                         };
                 }
 
-                // Autosave on the server
+                /**
+                 * @summary Auto saves the post on the server.
+                 *
+                 * @since 3.9.0
+                 *
+                 * @returns {Object} {
+                 *      {
+                 *              tempBlockSave: tempBlockSave,
+                 *              triggerSave: triggerSave,
+                 *              postChanged: postChanged,
+                 *              suspend: suspend,
+                 *              resume: resume
+                 *              }
+                 *      } The object all functions for autosave.
+                 */
                 function autosaveServer() {
                         var _blockSave, _blockSaveTimer, previousCompareString, lastCompareString,
                                 nextRun = 0,
                                 isSuspended = false;
 
-                        // Block saving for the next 10 sec.
+
+                        /**
+                         * @summary  Blocks saving for the next 10 seconds.
+                         *
+                         * @since 3.9.0
+                         *
+                         * @returns {void}
+                         */
                         function tempBlockSave() {
                                 _blockSave = true;
                                 window.clearTimeout( _blockSaveTimer );
@@ -443 +602 @@
                                 }, 10000 );
                         }
 
+                        /**
+                         * @summary Sets isSuspended to true.
+                         *
+                         * @since 3.9.0
+                         *
+                         * @returns {void}
+                         */
                         function suspend() {
                                 isSuspended = true;
                         }
 
+                        /**
+                         * @summary Sets isSuspended to false.
+                         *
+                         * @since 3.9.0
+                         *
+                         * @returns {void}
+                         */
                         function resume() {
                                 isSuspended = false;
                         }
 
-                        // Runs on heartbeat-response
+                        /**
+                         * @summary Triggers the autosave with the post data.
+                         *
+                         * @since 3.9.0
+                         *
+                         * @param {Object} data The post data.
+                         *
+                         * @returns {void}
+                         */
                         function response( data ) {
                                 _schedule();
                                 _blockSave = false;
@@ -468 +649 @@
                         }
 
                         /**
-                         * Save immediately
+                         * @summary Saves immediately.
+                         *
+                         * Resets the timing and tells heartbeat to connect now.
                          *
-                         * Resets the timing and tells heartbeat to connect now
+                         * @since 3.9.0
                          *
-                         * @return void
+                         * @returns {void}
                          */
                         function triggerSave() {
                                 nextRun = 0;
@@ -480 +663 @@
                         }
 
                         /**
-                         * Checks if the post content in the textarea has changed since page load.
+                         * @summary Checks if the post content in the textarea has changed since page load.
                          *
                          * This also happens when TinyMCE is active and editor.save() is triggered by
                          * wp.autosave.getPostData().
                          *
-                         * @return bool
+                         * @since 3.9.0
+                         *
+                         * @return {boolean} True if the post has been changed.
                          */
                         function postChanged() {
                                 return getCompareString() !== initialCompareString;
                         }
 
-                        // Runs on 'heartbeat-send'
+                        /**
+                         * @summary Checks if the post can be saved or not.
+                         *
+                         * If the post hasn't changed or it cannot be updated,
+                         * because the autosave is blocked or suspended, the function returns false.
+                         *
+                         * @since 3.9.0
+                         *
+                         * @returns {Object} Returns the post data.
+                         */
                         function save() {
                                 var postData, compareString;
 
@@ -529 +723 @@
                                 return postData;
                         }
 
+                        /**
+                         * @summary Sets the next run, based on the autosave interval.
+                         *
+                         * @private
+                         *
+                         * @since 3.9.0
+                         *
+                         * @returns {void}
+                         */
                         function _schedule() {
                                 nextRun = ( new Date() ).getTime() + ( autosaveL10n.autosaveInterval * 1000 ) || 60000;
                         }
 
+                        /**
+                         * @summary Sets the autosaveData on the autosave heartbeat.
+                         *
+                         * @since 3.9.0
+                         *
+                         * @returns {void}
+                         */
                         $document.on( 'heartbeat-send.autosave', function( event, data ) {
                                 var autosaveData = save();
 
                                 if ( autosaveData ) {
                                         data.wp_autosave = autosaveData;
                                 }
+
+                                /**
+                                 * @summary Triggers the autosave of the post with the autosave data
+                                 * on the autosave heartbeat.
+                                 *
+                                 * @since 3.9.0
+                                 *
+                                 * @returns {void}
+                                 */
                         }).on( 'heartbeat-tick.autosave', function( event, data ) {
                                 if ( data.wp_autosave ) {
                                         response( data.wp_autosave );
                                 }
+                                /**
+                                 * @summary Disables buttons and throws a notice when the connection is lost.
+                                 *
+                                 * @since 3.9.0
+                                 *
+                                 * @returns {void}
+                                 */
                         }).on( 'heartbeat-connection-lost.autosave', function( event, error, status ) {
+
                                 // When connection is lost, keep user from submitting changes.
                                 if ( 'timeout' === error || 603 === status ) {
                                         var $notice = $('#lost-connection-notice');
@@ -555 +782 @@
                                         $notice.show();
                                         disableButtons();
                                 }
+
+                                /**
+                                 * @summary Enables buttons when the connection is restored.
+                                 *
+                                 * @since 3.9.0
+                                 *
+                                 * @returns {void}
+                                 */
                         }).on( 'heartbeat-connection-restored.autosave', function() {
                                 $('#lost-connection-notice').hide();
                                 enableButtons();
@@ -571 +806 @@
                         };
                 }
 
-                // Wait for TinyMCE to initialize plus 1 sec. for any external css to finish loading,
-                // then 'save' to the textarea before setting initialCompareString.
-                // This avoids any insignificant differences between the initial textarea content and the content
-                // extracted from the editor.
+                /**
+                 * @summary Sets the autosave time out.
+                 *
+                 * Wait for TinyMCE to initialize plus 1 second. for any external css to finish loading,
+                 * then save to the textarea before setting initialCompareString.
+                 * This avoids any insignificant differences between the initial textarea content and the content
+                 * extracted from the editor.
+                 *
+                 * @since 3.9.0
+                 *
+                 * @returns {void}
+                 */
                 $document.on( 'tinymce-editor-init.autosave', function( event, editor ) {
                         if ( editor.id === 'content' ) {
                                 window.setTimeout( function() {