From 225de4e6eb6ef4ae0de4a6945aab6556433acad9 Mon Sep 17 00:00:00 2001 From: atimmer Date: Thu, 20 Jun 2019 14:45:51 +0000 Subject: [PATCH] Docs: Improve JSDoc for `admin/edit-comments.js`. Props manuelaugustin, diedeexterkate, thulshof, Xyfi, ireneyoast. Fixes #47581. Built from https://develop.svn.wordpress.org/trunk@45558 git-svn-id: http://core.svn.wordpress.org/trunk@45369 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-admin/js/edit-comments.js | 348 +++++++++++++++++++++++++++++++++-- wp-includes/version.php | 2 +- 2 files changed, 338 insertions(+), 12 deletions(-) diff --git a/wp-admin/js/edit-comments.js b/wp-admin/js/edit-comments.js index e20a9917d7..b4745f4439 100644 --- a/wp-admin/js/edit-comments.js +++ b/wp-admin/js/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. * - * @returns {boolean} + * @since 4.6.0 + * + * @memberof commentReply + * + * @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"]'); diff --git a/wp-includes/version.php b/wp-includes/version.php index 92f4a55f0b..55fee208c7 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -13,7 +13,7 @@ * * @global string $wp_version */ -$wp_version = '5.3-alpha-45557'; +$wp_version = '5.3-alpha-45558'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.