WordPress.org

Make WordPress Core

Changeset 45558


Ignore:
Timestamp:
06/20/2019 02:44:30 PM (5 hours ago)
Author:
atimmer
Message:

Docs: Improve JSDoc for admin/edit-comments.js.

Props manuelaugustin, diedeexterkate, thulshof, Xyfi, ireneyoast.
Fixes #47581.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/js/_enqueues/admin/edit-comments.js

    r45553 r45558  
    11/**
     2 * Handles updating and editing comments.
     3 *
     4 * @file This file contains functionality for the admin comments page.
     5 * @since 3.5.0
    26 * @output wp-admin/js/edit-comments.js
    37 */
     
    1216    titleDiv, titleRegEx;
    1317
     18    /**
     19     * Extracts a number from the content of a jQuery element.
     20     *
     21     * @since 2.9.0
     22     * @access private
     23     *
     24     * @param {jQuery} el jQuery element.
     25     *
     26     * @return {number} The number found in the given element.
     27     */
    1428    getCount = function(el) {
    1529        var n = parseInt( el.html().replace(/[^0-9]+/g, ''), 10 );
     
    2034    };
    2135
     36    /**
     37     * Updates an html element with a localized number string.
     38     *
     39     * @since 2.9.0
     40     * @access private
     41     *
     42     * @param {jQuery} el The jQuery element to update.
     43     * @param {number} n Number to be put in the element.
     44     *
     45     * @return {void}
     46     */
    2247    updateCount = function(el, n) {
    2348        var n1 = '';
     
    3661    };
    3762
     63    /**
     64     * Updates the number of approved comments on a specific post and the filter bar.
     65     *
     66     * @since 4.4.0
     67     * @access private
     68     *
     69     * @param {number} diff The amount to lower or raise the approved count with.
     70     * @param {number} commentPostId The ID of the post to be updated.
     71     *
     72     * @return {void}
     73     */
    3874    updateApproved = function( diff, commentPostId ) {
    3975        var postSelector = '.post-com-count-' + commentPostId,
     
    4985        }
    5086
    51         // cache selectors to not get dupes
     87        // Cache selectors to not get duplicates.
    5288        approved = $( 'span.' + approvedClass, postSelector );
    5389        noComments = $( 'span.' + noClass, postSelector );
     
    77113    };
    78114
     115    /**
     116     * Updates a number count in all matched HTML elements
     117     *
     118     * @since 4.4.0
     119     * @access private
     120     *
     121     * @param {string} selector The jQuery selector for elements to update a count
     122     *                          for.
     123     * @param {number} diff The amount to lower or raise the count with.
     124     *
     125     * @return {void}
     126     */
    79127    updateCountText = function( selector, diff ) {
    80128        $( selector ).each(function() {
     
    87135    };
    88136
     137    /**
     138     * Updates a text about comment count on the dashboard.
     139     *
     140     * @since 4.4.0
     141     * @access private
     142     *
     143     * @param {Object} response Ajax response from the server that includes a
     144     *                          translated "comment count" message.
     145     *
     146     * @return {void}
     147     */
    89148    updateDashboardText = function( response ) {
    90149        if ( ! isDashboard || ! response || ! response.i18n_comments_text ) {
     
    100159     * @since 5.2.0
    101160     *
    102      * @param {object} response Ajax response from the server.
     161     * @param {object} response Ajax response from the server that includes a
     162     *                          translated "comments in moderation" message.
    103163     *
    104164     * @return {void}
     
    118178    };
    119179
     180    /**
     181     * Updates the title of the document with the number comments to be approved.
     182     *
     183     * @since 4.4.0
     184     * @access private
     185     *
     186     * @param {number} diff The amount to lower or raise the number of to be
     187     *                      approved comments with.
     188     *
     189     * @return {void}
     190     */
    120191    updateHtmlTitle = function( diff ) {
    121192        var newTitle, regExMatch, titleCount, commentFrag;
     
    151222    };
    152223
     224    /**
     225     * Updates the number of pending comments on a specific post and the filter bar.
     226     *
     227     * @since 3.2.0
     228     * @access private
     229     *
     230     * @param {number} diff The amount to lower or raise the pending count with.
     231     * @param {number} commentPostId The ID of the post to be updated.
     232     *
     233     * @return {void}
     234     */
    153235    updatePending = function( diff, commentPostId ) {
    154236        var postSelector = '.post-com-count-' + commentPostId,
     
    207289    };
    208290
     291/**
     292 * Initializes the comments list.
     293 *
     294 * @since 4.4.0
     295 *
     296 * @global
     297 *
     298 * @return {void}
     299 */
    209300window.setCommentsList = function() {
    210301    var totalInput, perPageInput, pageInput, dimAfter, delBefore, updateTotalCount, delAfter, refillTheExtraList, diff,
     
    215306    pageInput = $('input[name="_page"]', '#comments-form');
    216307
    217     // Updates the current total (stored in the _total input)
     308    /**
     309     * Updates the total with the latest count.
     310     *
     311     * The time parameter makes sure that we only update the total if this value is
     312     * a newer value than we previously received.
     313     *
     314     * The time and setConfidentTime parameters make sure that we only update the
     315     * total when necessary. So a value that has been generated earlier will not
     316     * update the total.
     317     *
     318     * @since 2.8.0
     319     * @access private
     320     *
     321     * @param {number} total Total number of comments.
     322     * @param {number} time Unix timestamp of response.
     323     * @param {boolean} setConfidentTime Whether to update the last confident time
     324     *                                   with the given time.
     325     *
     326     * @return {void}
     327     */
    218328    updateTotalCount = function( total, time, setConfidentTime ) {
    219329        if ( time < lastConfidentTime )
     
    226336    };
    227337
    228     // this fires when viewing "All"
     338    /**
     339     * Changes DOM that need to be changed after a list item has been dimmed.
     340     *
     341     * @since 2.5.0
     342     * @access private
     343     *
     344     * @param {Object} r Ajax response object.
     345     * @param {Object} settings Settings for the wpList object.
     346     *
     347     * @return {void}
     348     */
    229349    dimAfter = function( r, settings ) {
    230350        var editRow, replyID, replyButton, response,
     
    266386    };
    267387
    268     // Send current total, page, per_page and url
     388    /**
     389     * Handles marking a comment as spam or trashing the comment.
     390     *
     391     * Is executed in the list delBefore hook.
     392     *
     393     * @since 2.8.0
     394     * @access private
     395     *
     396     * @param {Object} settings Settings for the wpList object.
     397     * @param {HTMLElement} list Comments table element.
     398     *
     399     * @return {Object} The settings object.
     400     */
    269401    delBefore = function( settings, list ) {
    270402        var note, id, el, n, h, a, author,
     
    325457    };
    326458
    327     // In admin-ajax.php, we send back the unix time stamp instead of 1 on success
     459    /**
     460     * Handles actions that need to be done after marking as spam or thrashing a
     461     * comment.
     462     *
     463     * The ajax requests return the unix time stamp a comment was marked as spam or
     464     * trashed. We use this to have a correct total amount of comments.
     465     *
     466     * @since 2.5.0
     467     * @access private
     468     *
     469     * @param {Object} r Ajax response object.
     470     * @param {Object} settings Settings for the wpList object.
     471     *
     472     * @return {void}
     473     */
    328474    delAfter = function( r, settings ) {
    329475        var total_items_i18n, total, animated, animatedCallback,
     
    546692    };
    547693
     694    /**
     695     * Retrieves additional comments to populate the extra list.
     696     *
     697     * @since 3.1.0
     698     * @access private
     699     *
     700     * @param {boolean} [ev] Repopulate the extra comments list if true.
     701     *
     702     * @return {void}
     703     */
    548704    refillTheExtraList = function(ev) {
    549705        var args = $.query.get(), total_pages = $('.total-pages').text(), per_page = $('input[name="_per_page"]', '#comments-form').val();
     
    589745    };
    590746
     747    /**
     748     * Globally available jQuery object referring to the extra comments list.
     749     *
     750     * @global
     751     */
    591752    window.theExtraList = $('#the-extra-comment-list').wpList( { alt: '', delColor: 'none', addColor: 'none' } );
     753
     754    /**
     755     * Globally available jQuery object referring to the comments list.
     756     *
     757     * @global
     758     */
    592759    window.theList = $('#the-comment-list').wpList( { alt: '', delBefore: delBefore, dimAfter: dimAfter, delAfter: delAfter, addColor: 'none' } )
    593760        .bind('wpListDelEnd', function(e, s){
     
    599766};
    600767
     768/**
     769 * Object containing functionality regarding the comment quick editor and reply
     770 * editor.
     771 *
     772 * @since 2.7.0
     773 *
     774 * @global
     775 */
    601776window.commentReply = {
    602777    cid : '',
     
    604779    originalContent : '',
    605780
     781    /**
     782     * Initializes the comment reply functionality.
     783     *
     784     * @memberof commentReply
     785     *
     786     * @since 2.7.0
     787     */
    606788    init : function() {
    607789        var row = $('#replyrow');
     
    630812    },
    631813
     814    /**
     815     * Adds doubleclick event handler to the given comment list row.
     816     *
     817     * The double-click event will toggle the comment edit or reply form.
     818     *
     819     * @since 2.7.0
     820     *
     821     * @memberof commentReply
     822     *
     823     * @param {Object} r The row to add double click handlers to.
     824     *
     825     * @return {void}
     826     */
    632827    addEvents : function(r) {
    633828        r.each(function() {
     
    638833    },
    639834
     835    /**
     836     * Opens the quick edit for the given element.
     837     *
     838     * @since 2.7.0
     839     *
     840     * @memberof commentReply
     841     *
     842     * @param {HTMLElement} el The element you want to open the quick editor for.
     843     *
     844     * @return {void}
     845     */
    640846    toggle : function(el) {
    641847        if ( 'none' !== $( el ).css( 'display' ) && ( $( '#replyrow' ).parent().is('#com-reply') || window.confirm( adminCommentsL10n.warnQuickEdit ) ) ) {
     
    644850    },
    645851
     852    /**
     853     * Closes the comment quick edit or reply form and undoes any changes.
     854     *
     855     * @since 2.7.0
     856     *
     857     * @memberof commentReply
     858     *
     859     * @return {void}
     860     */
    646861    revert : function() {
    647862
     
    654869    },
    655870
     871    /**
     872     * Closes the comment quick edit or reply form and undoes any changes.
     873     *
     874     * @since 2.7.0
     875     *
     876     * @memberof commentReply
     877     *
     878     * @return {void}
     879     */
    656880    close : function() {
    657881        var commentRow = $(),
    658882            replyRow = $( '#replyrow' );
    659883
    660         // replyrow is not showing?
     884        // Return if the replyrow is not showing.
    661885        if ( replyRow.parent().is( '#com-reply' ) ) {
    662886            return;
     
    689913
    690914        // reset the Quicktags buttons
    691         if ( typeof QTags != 'undefined' )
     915        if ( typeof QTags != 'undefined' )
    692916            QTags.closeAllTags('replycontent');
    693917
     
    707931    },
    708932
     933    /**
     934     * Opens the comment quick edit or reply form.
     935     *
     936     * @since 2.7.0
     937     *
     938     * @memberof commentReply
     939     *
     940     * @param {number} comment_id The comment id to open an editor for.
     941     * @param {number} post_id The post id to open an editor for.
     942     * @param {string} action The action to perform. Either 'edit' or 'replyto'.
     943     *
     944     * @return {boolean} Always false.
     945     */
    709946    open : function(comment_id, post_id, action) {
    710947        var editRow, rowData, act, replyButton, editHeight,
     
    8001037    },
    8011038
     1039    /**
     1040     * Submits the comment quick edit or reply form.
     1041     *
     1042     * @since 2.7.0
     1043     *
     1044     * @memberof commentReply
     1045     *
     1046     * @return {void}
     1047     */
    8021048    send : function() {
    8031049        var post = {},
     
    8291075    },
    8301076
     1077    /**
     1078     * Shows the new or updated comment or reply.
     1079     *
     1080     * This function needs to be passed the ajax result as received from the server.
     1081     * It will handle the response and show the comment that has just been saved to
     1082     * the server.
     1083     *
     1084     * @since 2.7.0
     1085     *
     1086     * @memberof commentReply
     1087     *
     1088     * @param {Object} xml Ajax response object.
     1089     *
     1090     * @return {void}
     1091     */
    8311092    show : function(xml) {
    8321093        var t = this, r, c, id, bg, pid;
     
    8901151    },
    8911152
     1153    /**
     1154     * Shows an error for the failed comment update or reply.
     1155     *
     1156     * @since 2.7.0
     1157     *
     1158     * @memberof commentReply
     1159     *
     1160     * @param {string} r The Ajax response.
     1161     *
     1162     * @return {void}
     1163     */
    8921164    error : function(r) {
    8931165        var er = r.statusText,
     
    9061178    },
    9071179
     1180    /**
     1181     * Opens the add comments form in the comments metabox on the post edit page.
     1182     *
     1183     * @since 3.4.0
     1184     *
     1185     * @memberof commentReply
     1186     *
     1187     * @param {number} post_id The post id.
     1188     *
     1189     * @return {void}
     1190     */
    9081191    addcomment: function(post_id) {
    9091192        var t = this;
     
    9171200
    9181201    /**
    919      * Alert the user if they have unsaved changes on a comment that will be
    920      * lost if they proceed.
    921      *
    922      * @returns {boolean}
     1202     * Alert the user if they have unsaved changes on a comment that will be lost if
     1203     * they proceed with the intended action.
     1204     *
     1205     * @since 4.6.0
     1206     *
     1207     * @memberof commentReply
     1208     *
     1209     * @return {boolean} Whether it is safe the continue with the intended action.
    9231210     */
    9241211    discardCommentChanges: function() {
     
    9441231
    9451232    if ( typeof $.table_hotkeys != 'undefined' ) {
     1233        /**
     1234         * Creates a function that navigates to a previous or next page.
     1235         *
     1236         * @since 2.7.0
     1237         * @access private
     1238         *
     1239         * @param {string} which What page to navigate to: either next or prev.
     1240         *
     1241         * @return {Function} The function that executes the navigation.
     1242         */
    9461243        make_hotkeys_redirect = function(which) {
    9471244            return function() {
     
    9551252        };
    9561253
     1254        /**
     1255         * Navigates to the edit page for the selected comment.
     1256         *
     1257         * @since 2.7.0
     1258         * @access private
     1259         *
     1260         * @param {Object} event       The event that triggered this action.
     1261         * @param {Object} current_row A jQuery object of the selected row.
     1262         *
     1263         * @return {void}
     1264         */
    9571265        edit_comment = function(event, current_row) {
    9581266            window.location = $('span.edit a', current_row).attr('href');
    9591267        };
    9601268
     1269        /**
     1270         * Toggles all comments on the screen, for bulk actions.
     1271         *
     1272         * @since 2.7.0
     1273         * @access private
     1274         *
     1275         * @return {void}
     1276         */
    9611277        toggle_all = function() {
    9621278            $('#cb-select-all-1').data( 'wp-toggle', 1 ).trigger( 'click' ).removeData( 'wp-toggle' );
    9631279        };
    9641280
     1281        /**
     1282         * Creates a bulk action function that is executed on all selected comments.
     1283         *
     1284         * @since 2.7.0
     1285         * @access private
     1286         *
     1287         * @param {string} value The name of the action to execute.
     1288         *
     1289         * @return {Function} The function that executes the bulk action.
     1290         */
    9651291        make_bulk = function(value) {
    9661292            return function() {
Note: See TracChangeset for help on using the changeset viewer.