Upstream
/
WordPress
mirror of https://github.com/WordPress/WordPress.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

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
This commit is contained in:
atimmer 2019-06-20 14:45:51 +00:00
parent bcc4ecb1f6
commit 225de4e6eb
2 changed files with 338 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

348
wp-admin/js/edit-comments.js
View File

@ -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"]');

2
wp-includes/version.php
View File

@ -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.