Changeset 45558

Timestamp:

06/20/2019 02:44:30 PM (4 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 @@
 /**
+ * Handles updating and editing comments.
+ *
+ * @file This file contains functionality for the admin comments page.
+ * @since 3.5.0
  * @output wp-admin/js/edit-comments.js
  */
@@ -12 +16 @@
     titleDiv, titleRegEx;
 
+    /**
+     * Extracts a number from the content of a jQuery element.
+     *
+     * @since 2.9.0
+     * @access private
+     *
+     * @param {jQuery} el jQuery element.
+     *
+     * @return {number} The number found in the given element.
+     */
     getCount = function(el) {
         var n = parseInt( el.html().replace(/[^0-9]+/g, ''), 10 );
@@ -20 +34 @@
     };
 
+    /**
+     * Updates an html element with a localized number string.
+     *
+     * @since 2.9.0
+     * @access private
+     *
+     * @param {jQuery} el The jQuery element to update.
+     * @param {number} n Number to be put in the element.
+     *
+     * @return {void}
+     */
     updateCount = function(el, n) {
         var n1 = '';
@@ -36 +61 @@
     };
 
+    /**
+     * Updates the number of approved comments on a specific post and the filter bar.
+     *
+     * @since 4.4.0
+     * @access private
+     *
+     * @param {number} diff The amount to lower or raise the approved count with.
+     * @param {number} commentPostId The ID of the post to be updated.
+     *
+     * @return {void}
+     */
     updateApproved = function( diff, commentPostId ) {
         var postSelector = '.post-com-count-' + commentPostId,
@@ -49 +85 @@
         }
 
-        // cache selectors to not get dupes
+        // Cache selectors to not get duplicates.
         approved = $( 'span.' + approvedClass, postSelector );
         noComments = $( 'span.' + noClass, postSelector );
@@ -77 +113 @@
     };
 
+    /**
+     * Updates a number count in all matched HTML elements
+     *
+     * @since 4.4.0
+     * @access private
+     *
+     * @param {string} selector The jQuery selector for elements to update a count
+     *                          for.
+     * @param {number} diff The amount to lower or raise the count with.
+     *
+     * @return {void}
+     */
     updateCountText = function( selector, diff ) {
         $( selector ).each(function() {
@@ -87 +135 @@
     };
 
+    /**
+     * Updates a text about comment count on the dashboard.
+     *
+     * @since 4.4.0
+     * @access private
+     *
+     * @param {Object} response Ajax response from the server that includes a
+     *                          translated "comment count" message.
+     *
+     * @return {void}
+     */
     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 @@
     };
 
+    /**
+     * Updates the title of the document with the number comments to be approved.
+     *
+     * @since 4.4.0
+     * @access private
+     *
+     * @param {number} diff The amount to lower or raise the number of to be
+     *                      approved comments with.
+     *
+     * @return {void}
+     */
     updateHtmlTitle = function( diff ) {
         var newTitle, regExMatch, titleCount, commentFrag;
@@ -151 +222 @@
     };
 
+    /**
+     * Updates the number of pending comments on a specific post and the filter bar.
+     *
+     * @since 3.2.0
+     * @access private
+     *
+     * @param {number} diff The amount to lower or raise the pending count with.
+     * @param {number} commentPostId The ID of the post to be updated.
+     *
+     * @return {void}
+     */
     updatePending = function( diff, commentPostId ) {
         var postSelector = '.post-com-count-' + commentPostId,
@@ -207 +289 @@
     };
 
+/**
+ * Initializes the comments list.
+ *
+ * @since 4.4.0
+ *
+ * @global
+ *
+ * @return {void}
+ */
 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 @@
     };
 
+    /**
+     * Retrieves additional comments to populate the extra list.
+     *
+     * @since 3.1.0
+     * @access private
+     *
+     * @param {boolean} [ev] Repopulate the extra comments list if true.
+     *
+     * @return {void}
+     */
     refillTheExtraList = function(ev) {
         var args = $.query.get(), total_pages = $('.total-pages').text(), per_page = $('input[name="_per_page"]', '#comments-form').val();
@@ -589 +745 @@
     };
 
+    /**
+     * Globally available jQuery object referring to the extra comments list.
+     *
+     * @global
+     */
     window.theExtraList = $('#the-extra-comment-list').wpList( { alt: '', delColor: 'none', addColor: 'none' } );
+
+    /**
+     * Globally available jQuery object referring to the comments list.
+     *
+     * @global
+     */
     window.theList = $('#the-comment-list').wpList( { alt: '', delBefore: delBefore, dimAfter: dimAfter, delAfter: delAfter, addColor: 'none' } )
         .bind('wpListDelEnd', function(e, s){
@@ -599 +766 @@
 };
 
+/**
+ * Object containing functionality regarding the comment quick editor and reply
+ * editor.
+ *
+ * @since 2.7.0
+ *
+ * @global
+ */
 window.commentReply = {
     cid : '',
@@ -604 +779 @@
     originalContent : '',
 
+    /**
+     * Initializes the comment reply functionality.
+     *
+     * @memberof commentReply
+     *
+     * @since 2.7.0
+     */
     init : function() {
         var row = $('#replyrow');
@@ -630 +812 @@
     },
 
+    /**
+     * Adds doubleclick event handler to the given comment list row.
+     *
+     * The double-click event will toggle the comment edit or reply form.
+     *
+     * @since 2.7.0
+     *
+     * @memberof commentReply
+     *
+     * @param {Object} r The row to add double click handlers to.
+     *
+     * @return {void}
+     */
     addEvents : function(r) {
         r.each(function() {
@@ -638 +833 @@
     },
 
+    /**
+     * Opens the quick edit for the given element.
+     *
+     * @since 2.7.0
+     *
+     * @memberof commentReply
+     *
+     * @param {HTMLElement} el The element you want to open the quick editor for.
+     *
+     * @return {void}
+     */
     toggle : function(el) {
         if ( 'none' !== $( el ).css( 'display' ) && ( $( '#replyrow' ).parent().is('#com-reply') || window.confirm( adminCommentsL10n.warnQuickEdit ) ) ) {
@@ -644 +850 @@
     },
 
+    /**
+     * Closes the comment quick edit or reply form and undoes any changes.
+     *
+     * @since 2.7.0
+     *
+     * @memberof commentReply
+     *
+     * @return {void}
+     */
     revert : function() {
 
@@ -654 +869 @@
     },
 
+    /**
+     * Closes the comment quick edit or reply form and undoes any changes.
+     *
+     * @since 2.7.0
+     *
+     * @memberof commentReply
+     *
+     * @return {void}
+     */
     close : function() {
         var commentRow = $(),
             replyRow = $( '#replyrow' );
 
-        // replyrow is not showing?
+        // Return if the 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 @@
     },
 
+    /**
+     * Opens the comment quick edit or reply form.
+     *
+     * @since 2.7.0
+     *
+     * @memberof commentReply
+     *
+     * @param {number} comment_id The comment id to open an editor for.
+     * @param {number} post_id The post id to open an editor for.
+     * @param {string} action The action to perform. Either 'edit' or 'replyto'.
+     *
+     * @return {boolean} Always false.
+     */
     open : function(comment_id, post_id, action) {
         var editRow, rowData, act, replyButton, editHeight,
@@ -800 +1037 @@
     },
 
+    /**
+     * Submits the comment quick edit or reply form.
+     *
+     * @since 2.7.0
+     *
+     * @memberof commentReply
+     *
+     * @return {void}
+     */
     send : function() {
         var post = {},
@@ -829 +1075 @@
     },
 
+    /**
+     * Shows the new or updated comment or reply.
+     *
+     * This function needs to be passed the ajax result as received from the server.
+     * It will handle the response and show the comment that has just been saved to
+     * the server.
+     *
+     * @since 2.7.0
+     *
+     * @memberof commentReply
+     *
+     * @param {Object} xml Ajax response object.
+     *
+     * @return {void}
+     */
     show : function(xml) {
         var t = this, r, c, id, bg, pid;
@@ -890 +1151 @@
     },
 
+    /**
+     * Shows an error for the failed comment update or reply.
+     *
+     * @since 2.7.0
+     *
+     * @memberof commentReply
+     *
+     * @param {string} r The Ajax response.
+     *
+     * @return {void}
+     */
     error : function(r) {
         var er = r.statusText,
@@ -906 +1178 @@
     },
 
+    /**
+     * Opens the add comments form in the comments metabox on the post edit page.
+     *
+     * @since 3.4.0
+     *
+     * @memberof commentReply
+     *
+     * @param {number} post_id The post id.
+     *
+     * @return {void}
+     */
     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' ) {
+        /**
+         * Creates a function that navigates to a previous or next page.
+         *
+         * @since 2.7.0
+         * @access private
+         *
+         * @param {string} which What page to navigate to: either next or prev.
+         *
+         * @return {Function} The function that executes the navigation.
+         */
         make_hotkeys_redirect = function(which) {
             return function() {
@@ -955 +1252 @@
         };
 
+        /**
+         * Navigates to the edit page for the selected comment.
+         *
+         * @since 2.7.0
+         * @access private
+         *
+         * @param {Object} event       The event that triggered this action.
+         * @param {Object} current_row A jQuery object of the selected row.
+         *
+         * @return {void}
+         */
         edit_comment = function(event, current_row) {
             window.location = $('span.edit a', current_row).attr('href');
         };
 
+        /**
+         * Toggles all comments on the screen, for bulk actions.
+         *
+         * @since 2.7.0
+         * @access private
+         *
+         * @return {void}
+         */
         toggle_all = function() {
             $('#cb-select-all-1').data( 'wp-toggle', 1 ).trigger( 'click' ).removeData( 'wp-toggle' );
         };
 
+        /**
+         * Creates a bulk action function that is executed on all selected comments.
+         *
+         * @since 2.7.0
+         * @access private
+         *
+         * @param {string} value The name of the action to execute.
+         *
+         * @return {Function} The function that executes the bulk action.
+         */
         make_bulk = function(value) {
             return function() {