WordPress.org
Get WordPress

Make WordPress Core

Changeset 41265


Ignore:
Timestamp:
08/18/2017 02:23:06 PM (7 years ago)
Author:
adamsilverstein
Message:

Docs: Improve JavaScript documentation in autosave.js.

Add and improve JSDOC blocks.

Props carolinegeven.
Fixes #41203.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-includes/js/autosave.js

    r38983 r41265  
    55};
    66
     7/**
     8 * @summary Adds autosave to the window object on dom ready.
     9 *
     10 * @since 3.9.0
     11 *
     12 * @param {jQuery} $ jQuery object.
     13 * @param {window} The window object.
     14 *
     15 */
    716( function( $, window ) {
     17    /**
     18     * @summary Auto saves the post.
     19     *
     20     * @since 3.9.0
     21     *
     22     * @returns {Object}
     23     *  {{
     24     *      getPostData: getPostData,
     25     *      getCompareString: getCompareString,
     26     *      disableButtons: disableButtons,
     27     *      enableButtons: enableButtons,
     28     *      local: ({hasStorage, getSavedPostData, save, suspend, resume}|*),
     29     *      server: ({tempBlockSave, triggerSave, postChanged, suspend, resume}|*)}
     30     *  }
     31     *  The object with all functions for autosave.
     32     */
    833    function autosave() {
    934        var initialCompareString,
    … …  
    1237
    1338        /**
    14          * Returns the data saved in both local and remote autosave
    15          *
    16          * @return object Object containing the post data
     39         * @summary Returns the data saved in both local and remote autosave.
     40         *
     41         * @since 3.9.0
     42         *
     43         * @param {string} type The type of autosave either local or remote.
     44         *
     45         * @returns {Object} Object containing the post data.
    1746         */
    1847        function getPostData( type ) {
    … …  
    2251                editor = getEditor();
    2352
    24             // Don't run editor.save() more often than every 3 sec.
     53            // Don't run editor.save() more often than every 3 seconds.
    2554            // It is resource intensive and might slow down typing in long posts on slow devices.
    2655            if ( editor && editor.isDirty() && ! editor.isHidden() && time - 3000 > lastTriggerSave ) {
    … …  
    7099        }
    71100
    72         // Concatenate title, content and excerpt. Used to track changes when auto-saving.
     101        /**
     102         * @summary Concatenates the title, content and excerpt.
     103         *
     104         * This is used to track changes when auto-saving.
     105         *
     106         * @since 3.9.0
     107         *
     108         * @param {Object} postData The object containing the post data.
     109         *
     110         * @returns {string} A concatenated string with title, content and excerpt.
     111         */
    73112        function getCompareString( postData ) {
    74113            if ( typeof postData === 'object' ) {
    … …  
    79118        }
    80119
     120        /**
     121         * @summary Disables save buttons.
     122         *
     123         * @since 3.9.0
     124         *
     125         * @returns {void}
     126         */
    81127        function disableButtons() {
    82128            $document.trigger('autosave-disable-buttons');
     129
    83130            // Re-enable 5 sec later. Just gives autosave a head start to avoid collisions.
    84131            setTimeout( enableButtons, 5000 );
    85132        }
    86133
     134        /**
     135         * @summary Enables save buttons.
     136         *
     137         * @since 3.9.0
     138         *
     139         * @returns {void}
     140         */
    87141        function enableButtons() {
    88142            $document.trigger( 'autosave-enable-buttons' );
    89143        }
    90144
     145        /**
     146         * @summary Gets the content editor.
     147         *
     148         * @since 4.6.0
     149         *
     150         * @returns {boolean|*} Returns either false if the editor is undefined,
     151         *                      or the instance of the content editor.
     152         */
    91153        function getEditor() {
    92154            return typeof tinymce !== 'undefined' && tinymce.get('content');
    93155        }
    94156
    95         // Autosave in localStorage
     157        /**
     158         * @summary Autosave in localStorage.
     159         *
     160         * @since 3.9.0
     161         *
     162         * @returns {
     163         * {
     164         *  hasStorage: *,
     165         *  getSavedPostData: getSavedPostData,
     166         *  save: save,
     167         *  suspend: suspend,
     168         *  resume: resume
     169         *  }
     170         * }
     171         * The object with all functions for local storage autosave.
     172         */
    96173        function autosaveLocal() {
    97174            var blog_id, post_id, hasStorage, intervalTimer,
    … …  
    99176                isSuspended = false;
    100177
    101             // Check if the browser supports sessionStorage and it's not disabled
     178            /**
     179             * @summary Checks if the browser supports sessionStorage and it's not disabled.
     180             *
     181             * @since 3.9.0
     182             *
     183             * @returns {boolean} True if the sessionStorage is supported and enabled.
     184             */
    102185            function checkStorage() {
    103186                var test = Math.random().toString(),
    … …  
    115198
    116199            /**
    117              * Initialize the local storage
    118              *
    119              * @return mixed False if no sessionStorage in the browser or an Object containing all postData for this blog
     200             * @summary Initializes the local storage.
     201             *
     202             * @since 3.9.0
     203             *
     204             * @returns {boolean|Object} False if no sessionStorage in the browser or an Object
     205             *                           containing all postData for this blog.
    120206             */
    121207            function getStorage() {
    … …  
    136222
    137223            /**
    138              * Set the storage for this blog
     224             * @summary Sets the storage for this blog.
    139225             *
    140226             * Confirms that the data was saved successfully.
    141227             *
    142              * @return bool
     228             * @since 3.9.0
     229             *
     230             * @returns {boolean} True if the data was saved successfully, false if it wasn't saved.
    143231             */
    144232            function setStorage( stored_obj ) {
    … …  
    155243
    156244            /**
    157              * Get the saved post data for the current post
    158              *
    159              * @return mixed False if no storage or no data or the postData as an Object
     245             * @summary Gets the saved post data for the current post.
     246             *
     247             * @since 3.9.0
     248             *
     249             * @returns {boolean|Object} False if no storage or no data or the postData as an Object.
    160250             */
    161251            function getSavedPostData() {
    … …  
    170260
    171261            /**
    172              * Set (save or delete) post data in the storage.
    173              *
    174              * If stored_data evaluates to 'false' the storage key for the current post will be removed
    175              *
    176              * $param stored_data The post data to store or null/false/empty to delete the key
    177              * @return bool
     262             * @summary Sets (save or delete) post data in the storage.
     263             *
     264             * If stored_data evaluates to 'false' the storage key for the current post will be removed.
     265             *
     266             * @since 3.9.0
     267             *
     268             * @param {Object|boolean|null} stored_data The post data to store or null/false/empty to delete the key.
     269             *
     270             * @returns {boolean} True if data is stored, false if data was removed.
    178271             */
    179272            function setData( stored_data ) {
    … …  
    195288            }
    196289
     290            /**
     291             * @summary Sets isSuspended to true.
     292             *
     293             * @since 3.9.0
     294             *
     295             * @returns {void}
     296             */
    197297            function suspend() {
    198298                isSuspended = true;
    199299            }
    200300
     301            /**
     302             * @summary Sets isSuspended to false.
     303             *
     304             * @since 3.9.0
     305             *
     306             * @returns {void}
     307             */
    201308            function resume() {
    202309                isSuspended = false;
    … …  
    204311
    205312            /**
    206              * Save post data for the current post
     313             * @summary Saves post data for the current post.
    207314             *
    208315             * Runs on a 15 sec. interval, saves when there are differences in the post title or content.
    209316             * When the optional data is provided, updates the last saved post data.
    210317             *
    211              * $param data optional Object The post data for saving, minimum 'post_title' and 'content'
    212              * @return bool
     318             * @since 3.9.0
     319             *
     320             * @param {Object} data The post data for saving, minimum 'post_title' and 'content'.
     321             *
     322             * @returns {boolean} Returns true when data has been saved, otherwise it returns false.
    213323             */
    214324            function save( data ) {
    … …  
    233343                }
    234344
    235                 // If the content, title and excerpt did not change since the last save, don't save again
     345                // If the content, title and excerpt did not change since the last save, don't save again.
    236346                if ( compareString === lastCompareString ) {
    237347                    return false;
    … …  
    249359            }
    250360
    251             // Run on DOM ready
     361            /**
     362             * @summary Initializes the auto save function.
     363             *
     364             * Checks whether the editor is active or not to use the editor events
     365             * to autosave, or uses the values from the elements to autosave.
     366             *
     367             * Runs on DOM ready.
     368             *
     369             * @since 3.9.0
     370             *
     371             * @returns {void}
     372             */
    252373            function run() {
    253374                post_id = $('#post_ID').val() || 0;
    … …  
    255376                // Check if the local post data is different than the loaded post data.
    256377                if ( $( '#wp-content-wrap' ).hasClass( 'tmce-active' ) ) {
     378
    257379                    // If TinyMCE loads first, check the post 1.5 sec. after it is ready.
    258380                    // By this time the content has been loaded in the editor and 'saved' to the textarea.
    … …  
    275397
    276398                    if ( editor && ! editor.isHidden() ) {
     399
    277400                        // Last onSubmit event in the editor, needs to run after the content has been moved to the textarea.
    278401                        editor.on( 'submit', function() {
    … …  
    296419            }
    297420
    298             // Strip whitespace and compare two strings
     421            /**
     422             * @summary Compares 2 strings.
     423             *
     424             * Removes whitespaces in the strings before comparing them.
     425             *
     426             * @since 3.9.0
     427             *
     428             * @param {string} str1 The first string.
     429             * @param {string} str2 The second string.
     430             * @returns {boolean} True if the strings are the same.
     431             */
    299432            function compare( str1, str2 ) {
    300433                function removeSpaces( string ) {
    … …  
    306439
    307440            /**
    308              * Check if the saved data for the current post (if any) is different than the loaded post data on the screen
     441             * @summary Checks if the saved data for the current post (if any) is different
     442             * than the loaded post data on the screen.
    309443             *
    310444             * Shows a standard message letting the user restore the post data if different.
    311445             *
    312              * @return void
     446             * @since 3.9.0
     447             *
     448             * @returns {void}
    313449             */
    314450            function checkPost() {
    … …  
    353489
    354490                if ( $newerAutosaveNotice.length ) {
     491
    355492                    // If there is a "server" autosave notice, hide it.
    356493                    // The data in the session storage is either the same or newer.
    … …  
    370507            }
    371508
    372             // Restore the current title, content and excerpt from postData.
     509            /**
     510             * @summary Restores the current title, content and excerpt from postData.
     511             *
     512             * @since 3.9.0
     513             *
     514             * @param {Object} postData The object containing all post data.
     515             *
     516             * @returns {boolean} True if the post is restored.
     517             */
    373518            function restorePost( postData ) {
    374519                var editor;
    … …  
    396541                        });
    397542                    } else {
     543
    398544                        // Make sure the Text editor is selected
    399545                        $( '#content-html' ).click();
    400546                        $( '#content' ).focus();
     547
    401548                        // Using document.execCommand() will let the user undo.
    402549                        document.execCommand( 'selectAll' );
    … …  
    428575        }
    429576
    430         // Autosave on the server
     577        /**
     578         * @summary Auto saves the post on the server.
     579         *
     580         * @since 3.9.0
     581         *
     582         * @returns {Object} {
     583         *  {
     584         *      tempBlockSave: tempBlockSave,
     585         *      triggerSave: triggerSave,
     586         *      postChanged: postChanged,
     587         *      suspend: suspend,
     588         *      resume: resume
     589         *      }
     590         *  } The object all functions for autosave.
     591         */
    431592        function autosaveServer() {
    432593            var _blockSave, _blockSaveTimer, previousCompareString, lastCompareString,
    … …  
    434595                isSuspended = false;
    435596
    436             // Block saving for the next 10 sec.
     597
     598            /**
     599             * @summary  Blocks saving for the next 10 seconds.
     600             *
     601             * @since 3.9.0
     602             *
     603             * @returns {void}
     604             */
    437605            function tempBlockSave() {
    438606                _blockSave = true;
    … …  
    444612            }
    445613
     614            /**
     615             * @summary Sets isSuspended to true.
     616             *
     617             * @since 3.9.0
     618             *
     619             * @returns {void}
     620             */
    446621            function suspend() {
    447622                isSuspended = true;
    448623            }
    449624
     625            /**
     626             * @summary Sets isSuspended to false.
     627             *
     628             * @since 3.9.0
     629             *
     630             * @returns {void}
     631             */
    450632            function resume() {
    451633                isSuspended = false;
    452634            }
    453635
    454             // Runs on heartbeat-response
     636            /**
     637             * @summary Triggers the autosave with the post data.
     638             *
     639             * @since 3.9.0
     640             *
     641             * @param {Object} data The post data.
     642             *
     643             * @returns {void}
     644             */
    455645            function response( data ) {
    456646                _schedule();
    … …  
    469659
    470660            /**
    471              * Save immediately
    472              *
    473              * Resets the timing and tells heartbeat to connect now
    474              *
    475              * @return void
     661             * @summary Saves immediately.
     662             *
     663             * Resets the timing and tells heartbeat to connect now.
     664             *
     665             * @since 3.9.0
     666             *
     667             * @returns {void}
    476668             */
    477669            function triggerSave() {
    … …  
    481673
    482674            /**
    483              * Checks if the post content in the textarea has changed since page load.
     675             * @summary Checks if the post content in the textarea has changed since page load.
    484676             *
    485677             * This also happens when TinyMCE is active and editor.save() is triggered by
    486678             * wp.autosave.getPostData().
    487679             *
    488              * @return bool
     680             * @since 3.9.0
     681             *
     682             * @return {boolean} True if the post has been changed.
    489683             */
    490684            function postChanged() {
    … …  
    492686            }
    493687
    494             // Runs on 'heartbeat-send'
     688            /**
     689             * @summary Checks if the post can be saved or not.
     690             *
     691             * If the post hasn't changed or it cannot be updated,
     692             * because the autosave is blocked or suspended, the function returns false.
     693             *
     694             * @since 3.9.0
     695             *
     696             * @returns {Object} Returns the post data.
     697             */
    495698            function save() {
    496699                var postData, compareString;
    … …  
    530733            }
    531734
     735            /**
     736             * @summary Sets the next run, based on the autosave interval.
     737             *
     738             * @private
     739             *
     740             * @since 3.9.0
     741             *
     742             * @returns {void}
     743             */
    532744            function _schedule() {
    533745                nextRun = ( new Date() ).getTime() + ( autosaveL10n.autosaveInterval * 1000 ) || 60000;
    534746            }
    535747
     748            /**
     749             * @summary Sets the autosaveData on the autosave heartbeat.
     750             *
     751             * @since 3.9.0
     752             *
     753             * @returns {void}
     754             */
    536755            $document.on( 'heartbeat-send.autosave', function( event, data ) {
    537756                var autosaveData = save();
    … …  
    540759                    data.wp_autosave = autosaveData;
    541760                }
     761
     762                /**
     763                 * @summary Triggers the autosave of the post with the autosave data
     764                 * on the autosave heartbeat.
     765                 *
     766                 * @since 3.9.0
     767                 *
     768                 * @returns {void}
     769                 */
    542770            }).on( 'heartbeat-tick.autosave', function( event, data ) {
    543771                if ( data.wp_autosave ) {
    544772                    response( data.wp_autosave );
    545773                }
     774                /**
     775                 * @summary Disables buttons and throws a notice when the connection is lost.
     776                 *
     777                 * @since 3.9.0
     778                 *
     779                 * @returns {void}
     780                 */
    546781            }).on( 'heartbeat-connection-lost.autosave', function( event, error, status ) {
     782
    547783                // When connection is lost, keep user from submitting changes.
    548784                if ( 'timeout' === error || 603 === status ) {
    … …  
    556792                    disableButtons();
    557793                }
     794
     795                /**
     796                 * @summary Enables buttons when the connection is restored.
     797                 *
     798                 * @since 3.9.0
     799                 *
     800                 * @returns {void}
     801                 */
    558802            }).on( 'heartbeat-connection-restored.autosave', function() {
    559803                $('#lost-connection-notice').hide();
    … …  
    572816        }
    573817
    574         // Wait for TinyMCE to initialize plus 1 sec. for any external css to finish loading,
    575         // then 'save' to the textarea before setting initialCompareString.
    576         // This avoids any insignificant differences between the initial textarea content and the content
    577         // extracted from the editor.
     818        /**
     819         * @summary Sets the autosave time out.
     820         *
     821         * Wait for TinyMCE to initialize plus 1 second. for any external css to finish loading,
     822         * then save to the textarea before setting initialCompareString.
     823         * This avoids any insignificant differences between the initial textarea content and the content
     824         * extracted from the editor.
     825         *
     826         * @since 3.9.0
     827         *
     828         * @returns {void}
     829         */
    578830        $document.on( 'tinymce-editor-init.autosave', function( event, editor ) {
    579831            if ( editor.id === 'content' ) {
    … …  
    584836            }
    585837        }).ready( function() {
     838
    586839            // Set the initial compare string in case TinyMCE is not used or not loaded first
    587840            initialCompareString = getCompareString();
Note: See TracChangeset for help on using the changeset viewer.