WordPress.org

Make WordPress Core

Changeset 41265


Ignore:
Timestamp:
08/18/17 14:23:06 (3 months 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.