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

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


git-svn-id: https://develop.svn.wordpress.org/trunk@45558 602fd350-edb4-49c9-b593-d223f7449a82

1 files changed, 337 insertions, 11 deletions

diff --git a/src/js/_enqueues/admin/edit-comments.js b/src/js/_enqueues/admin/edit-comments.js
index e20a9917d7..b4745f4439 100644
--- a/src/js/_enqueues/admin/edit-comments.js
+++ b/src/js/_enqueues/admin/edit-comments.js
@@ -1,4 +1,8 @@
 /**
+ * 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
  */
 
@@ -11,6 +15,16 @@ var getCount, updateCount, updateCountText, updatePending, updateApproved,
 	isDashboard = $('#dashboard_right_now').length,
 	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 );
 		if ( isNaN(n) ) {
@@ -19,6 +33,17 @@ var getCount, updateCount, updateCountText, updatePending, updateApproved,
 		return n;
 	};
 
+	/**
+	 * 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 = '';
 		if ( isNaN(n) ) {
@@ -35,6 +60,17 @@ var getCount, updateCount, updateCountText, updatePending, updateApproved,
 		el.html(n);
 	};
 
+	/**
+	 * 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,
 			noClass = 'comment-count-no-comments',
@@ -48,7 +84,7 @@ var getCount, updateCount, updateCountText, updatePending, updateApproved,
 			return;
 		}
 
-		// cache selectors to not get dupes
+		// Cache selectors to not get duplicates.
 		approved = $( 'span.' + approvedClass, postSelector );
 		noComments = $( 'span.' + noClass, postSelector );
 
@@ -76,6 +112,18 @@ var getCount, updateCount, updateCountText, updatePending, updateApproved,
 		});
 	};
 
+	/**
+	 * 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() {
 			var a = $(this), n = getCount(a) + diff;
@@ -86,6 +134,17 @@ var getCount, updateCount, updateCountText, updatePending, updateApproved,
 		});
 	};
 
+	/**
+	 * 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 ) {
 			return;
@@ -99,7 +158,8 @@ var getCount, updateCount, updateCountText, updatePending, updateApproved,
 	 *
 	 * @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}
 	 */
@@ -117,6 +177,17 @@ var getCount, updateCount, updateCountText, updatePending, updateApproved,
 		}
 	};
 
+	/**
+	 * 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;
 
@@ -150,6 +221,17 @@ var getCount, updateCount, updateCountText, updatePending, updateApproved,
 		document.title = newTitle;
 	};
 
+	/**
+	 * 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,
 			noClass = 'comment-count-no-pending',
@@ -206,6 +288,15 @@ var getCount, updateCount, updateCountText, updatePending, updateApproved,
 		});
 	};
 
+/**
+ * Initializes the comments list.
+ *
+ * @since 4.4.0
+ *
+ * @global
+ *
+ * @return {void}
+ */
 window.setCommentsList = function() {
 	var totalInput, perPageInput, pageInput, dimAfter, delBefore, updateTotalCount, delAfter, refillTheExtraList, diff,
 		lastConfidentTime = 0;
@@ -214,7 +305,26 @@ window.setCommentsList = function() {
 	perPageInput = $('input[name="_per_page"]', '#comments-form');
 	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 )
 			return;
@@ -225,7 +335,17 @@ window.setCommentsList = function() {
 		totalInput.val( total.toString() );
 	};
 
-	// 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,
 			c = $( '#' + settings.element );
@@ -265,7 +385,19 @@ window.setCommentsList = function() {
 		}
 	};
 
-	// 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,
 			action = false,
@@ -324,7 +456,21 @@ window.setCommentsList = function() {
 		return settings;
 	};
 
-	// 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,
 			response = true === settings.parsed ? {} : settings.parsed.responses[0],
@@ -545,6 +691,16 @@ window.setCommentsList = function() {
 		}
 	};
 
+	/**
+	 * 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();
 
@@ -588,7 +744,18 @@ window.setCommentsList = function() {
 		});
 	};
 
+	/**
+	 * 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){
 			var wpListsData = $(s.target).attr('data-wp-lists'), id = s.element.replace(/[^0-9]+/g, '');
@@ -598,11 +765,26 @@ window.setCommentsList = function() {
 		});
 };
 
+/**
+ * Object containing functionality regarding the comment quick editor and reply
+ * editor.
+ *
+ * @since 2.7.0
+ *
+ * @global
+ */
 window.commentReply = {
 	cid : '',
 	act : '',
 	originalContent : '',
 
+	/**
+	 * Initializes the comment reply functionality.
+	 *
+	 * @memberof commentReply
+	 *
+	 * @since 2.7.0
+	 */
 	init : function() {
 		var row = $('#replyrow');
 
@@ -629,6 +811,19 @@ window.commentReply = {
 		this.comments_listing = $('#comments-form > input[name="comment_status"]').val() || '';
 	},
 
+	/**
+	 * 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() {
 			$(this).find('.column-comment > p').dblclick(function(){
@@ -637,12 +832,32 @@ window.commentReply = {
 		});
 	},
 
+	/**
+	 * 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 ) ) ) {
 			$( el ).find( 'button.vim-q' ).click();
 		}
 	},
 
+	/**
+	 * Closes the comment quick edit or reply form and undoes any changes.
+	 *
+	 * @since 2.7.0
+	 *
+	 * @memberof commentReply
+	 *
+	 * @return {void}
+	 */
 	revert : function() {
 
 		if ( $('#the-comment-list #replyrow').length < 1 )
@@ -653,11 +868,20 @@ window.commentReply = {
 		});
 	},
 
+	/**
+	 * 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;
 		}
@@ -688,7 +912,7 @@ window.commentReply = {
 		}
 
 		// reset the Quicktags buttons
-		if ( typeof QTags != 'undefined' )
+ 		if ( typeof QTags != 'undefined' )
 			QTags.closeAllTags('replycontent');
 
 		$('#add-new-comment').css('display', '');
@@ -706,6 +930,19 @@ window.commentReply = {
 		this.originalContent = '';
 	},
 
+	/**
+	 * 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,
 			t = this,
@@ -799,6 +1036,15 @@ window.commentReply = {
 		return false;
 	},
 
+	/**
+	 * Submits the comment quick edit or reply form.
+	 *
+	 * @since 2.7.0
+	 *
+	 * @memberof commentReply
+	 *
+	 * @return {void}
+	 */
 	send : function() {
 		var post = {},
 			$errorNotice = $( '#replysubmit .error-notice' );
@@ -828,6 +1074,21 @@ window.commentReply = {
 		});
 	},
 
+	/**
+	 * 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;
 
@@ -889,6 +1150,17 @@ window.commentReply = {
 
 	},
 
+	/**
+	 * 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,
 			$errorNotice = $( '#replysubmit .notice-error' ),
@@ -905,6 +1177,17 @@ window.commentReply = {
 		}
 	},
 
+	/**
+	 * 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;
 
@@ -916,10 +1199,14 @@ window.commentReply = {
 	},
 
 	/**
-	 * Alert the user if they have unsaved changes on a comment that will be
-	 * lost if they proceed.
+	 * 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
 	 *
-	 * @returns {boolean}
+	 * @return {boolean} Whether it is safe the continue with the intended action.
 	 */
 	discardCommentChanges: function() {
 		var editRow = $( '#replyrow' );
@@ -943,6 +1230,16 @@ $(document).ready(function(){
 	});
 
 	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() {
 				var first_last, l;
@@ -954,14 +1251,43 @@ $(document).ready(function(){
 			};
 		};
 
+		/**
+		 * 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() {
 				var scope = $('select[name="action"]');