Changeset 45558

Timestamp:

06/20/2019 02:44:30 PM (5 years ago)

Author:

atimmer

Message:

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

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

File:

• trunk/src/js/_enqueues/admin/edit-comments.js (modified) (32 diffs)

trunk/src/js/_enqueues/admin/edit-comments.js

@@ -1 +1 @@
 /**
+
+
+
+
  * @output wp-admin/js/edit-comments.js
  */
@@ -12 +16 @@
     titleDiv, titleRegEx;
 
+
+
+
+
+
+
+
+
+
+
     getCount = function(el) {
         var n = parseInt( el.html().replace(/[^0-9]+/g, ''), 10 );
@@ -20 +34 @@
     };
 
+
+
+
+
+
+
+
+
+
+
+
     updateCount = function(el, n) {
         var n1 = '';
@@ -36 +61 @@
     };
 
+
+
+
+
+
+
+
+
+
+
+
     updateApproved = function( diff, commentPostId ) {
         var postSelector = '.post-com-count-' + commentPostId,
@@ -49 +85 @@
         }
 
-        // cache selectors to not get dupes
+        // 
         approved = $( 'span.' + approvedClass, postSelector );
         noComments = $( 'span.' + noClass, postSelector );
@@ -77 +113 @@
     };
 
+
+
+
+
+
+
+
+
+
+
+
+
     updateCountText = function( selector, diff ) {
         $( selector ).each(function() {
@@ -87 +135 @@
     };
 
+
+
+
+
+
+
+
+
+
+
+
     updateDashboardText = function( response ) {
         if ( ! isDashboard || ! response || ! response.i18n_comments_text ) {
@@ -100 +159 @@
      * @since 5.2.0
      *
-     * @param {object} response Ajax response from the server.
+     * @param {object} response Ajax response from the server that includes a
+     *                          translated "comments in moderation" message.
      *
      * @return {void}
@@ -118 +178 @@
     };
 
+
+
+
+
+
+
+
+
+
+
+
     updateHtmlTitle = function( diff ) {
         var newTitle, regExMatch, titleCount, commentFrag;
@@ -151 +222 @@
     };
 
+
+
+
+
+
+
+
+
+
+
+
     updatePending = function( diff, commentPostId ) {
         var postSelector = '.post-com-count-' + commentPostId,
@@ -207 +289 @@
     };
 
+
+
+
+
+
+
+
+
+
 window.setCommentsList = function() {
     var totalInput, perPageInput, pageInput, dimAfter, delBefore, updateTotalCount, delAfter, refillTheExtraList, diff,
@@ -215 +306 @@
     pageInput = $('input[name="_page"]', '#comments-form');
 
-    // Updates the current total (stored in the _total input)
+    /**
+     * Updates the total with the latest count.
+     *
+     * The time parameter makes sure that we only update the total if this value is
+     * a newer value than we previously received.
+     *
+     * The time and setConfidentTime parameters make sure that we only update the
+     * total when necessary. So a value that has been generated earlier will not
+     * update the total.
+     *
+     * @since 2.8.0
+     * @access private
+     *
+     * @param {number} total Total number of comments.
+     * @param {number} time Unix timestamp of response.
+     * @param {boolean} setConfidentTime Whether to update the last confident time
+     *                                   with the given time.
+     *
+     * @return {void}
+     */
     updateTotalCount = function( total, time, setConfidentTime ) {
         if ( time < lastConfidentTime )
@@ -226 +336 @@
     };
 
-    // this fires when viewing "All"
+    /**
+     * Changes DOM that need to be changed after a list item has been dimmed.
+     *
+     * @since 2.5.0
+     * @access private
+     *
+     * @param {Object} r Ajax response object.
+     * @param {Object} settings Settings for the wpList object.
+     *
+     * @return {void}
+     */
     dimAfter = function( r, settings ) {
         var editRow, replyID, replyButton, response,
@@ -266 +386 @@
     };
 
-    // Send current total, page, per_page and url
+    /**
+     * Handles marking a comment as spam or trashing the comment.
+     *
+     * Is executed in the list delBefore hook.
+     *
+     * @since 2.8.0
+     * @access private
+     *
+     * @param {Object} settings Settings for the wpList object.
+     * @param {HTMLElement} list Comments table element.
+     *
+     * @return {Object} The settings object.
+     */
     delBefore = function( settings, list ) {
         var note, id, el, n, h, a, author,
@@ -325 +457 @@
     };
 
-    // In admin-ajax.php, we send back the unix time stamp instead of 1 on success
+    /**
+     * Handles actions that need to be done after marking as spam or thrashing a
+     * comment.
+     *
+     * The ajax requests return the unix time stamp a comment was marked as spam or
+     * trashed. We use this to have a correct total amount of comments.
+     *
+     * @since 2.5.0
+     * @access private
+     *
+     * @param {Object} r Ajax response object.
+     * @param {Object} settings Settings for the wpList object.
+     *
+     * @return {void}
+     */
     delAfter = function( r, settings ) {
         var total_items_i18n, total, animated, animatedCallback,
@@ -546 +692 @@
     };
 
+
+
+
+
+
+
+
+
+
+
     refillTheExtraList = function(ev) {
         var args = $.query.get(), total_pages = $('.total-pages').text(), per_page = $('input[name="_per_page"]', '#comments-form').val();
@@ -589 +745 @@
     };
 
+
+
+
+
+
     window.theExtraList = $('#the-extra-comment-list').wpList( { alt: '', delColor: 'none', addColor: 'none' } );
+
+
+
+
+
+
     window.theList = $('#the-comment-list').wpList( { alt: '', delBefore: delBefore, dimAfter: dimAfter, delAfter: delAfter, addColor: 'none' } )
         .bind('wpListDelEnd', function(e, s){
@@ -599 +766 @@
 };
 
+
+
+
+
+
+
+
+
 window.commentReply = {
     cid : '',
@@ -604 +779 @@
     originalContent : '',
 
+
+
+
+
+
+
+
     init : function() {
         var row = $('#replyrow');
@@ -630 +812 @@
     },
 
+
+
+
+
+
+
+
+
+
+
+
+
+
     addEvents : function(r) {
         r.each(function() {
@@ -638 +833 @@
     },
 
+
+
+
+
+
+
+
+
+
+
+
     toggle : function(el) {
         if ( 'none' !== $( el ).css( 'display' ) && ( $( '#replyrow' ).parent().is('#com-reply') || window.confirm( adminCommentsL10n.warnQuickEdit ) ) ) {
@@ -644 +850 @@
     },
 
+
+
+
+
+
+
+
+
+
     revert : function() {
 
@@ -654 +869 @@
     },
 
+
+
+
+
+
+
+
+
+
     close : function() {
         var commentRow = $(),
             replyRow = $( '#replyrow' );
 
-        // replyrow is not showing?
+        // 
         if ( replyRow.parent().is( '#com-reply' ) ) {
             return;
@@ -689 +913 @@
 
         // reset the Quicktags buttons
-        if ( typeof QTags != 'undefined' )
+       if ( typeof QTags != 'undefined' )
             QTags.closeAllTags('replycontent');
 
@@ -707 +931 @@
     },
 
+
+
+
+
+
+
+
+
+
+
+
+
+
     open : function(comment_id, post_id, action) {
         var editRow, rowData, act, replyButton, editHeight,
@@ -800 +1037 @@
     },
 
+
+
+
+
+
+
+
+
+
     send : function() {
         var post = {},
@@ -829 +1075 @@
     },
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
     show : function(xml) {
         var t = this, r, c, id, bg, pid;
@@ -890 +1151 @@
     },
 
+
+
+
+
+
+
+
+
+
+
+
     error : function(r) {
         var er = r.statusText,
@@ -906 +1178 @@
     },
 
+
+
+
+
+
+
+
+
+
+
+
     addcomment: function(post_id) {
         var t = this;
@@ -917 +1200 @@
 
     /**
-     * Alert the user if they have unsaved changes on a comment that will be
-     * lost if they proceed.
-     *
-     * @returns {boolean}
+     * Alert the user if they have unsaved changes on a comment that will be lost if
+     * they proceed with the intended action.
+     *
+     * @since 4.6.0
+     *
+     * @memberof commentReply
+     *
+     * @return {boolean} Whether it is safe the continue with the intended action.
      */
     discardCommentChanges: function() {
@@ -944 +1231 @@
 
     if ( typeof $.table_hotkeys != 'undefined' ) {
+
+
+
+
+
+
+
+
+
+
         make_hotkeys_redirect = function(which) {
             return function() {
@@ -955 +1252 @@
         };
 
+
+
+
+
+
+
+
+
+
+
+
         edit_comment = function(event, current_row) {
             window.location = $('span.edit a', current_row).attr('href');
         };
 
+
+
+
+
+
+
+
+
         toggle_all = function() {
             $('#cb-select-all-1').data( 'wp-toggle', 1 ).trigger( 'click' ).removeData( 'wp-toggle' );
         };
 
+
+
+
+
+
+
+
+
+
+
         make_bulk = function(value) {
             return function() {