[ticket/10271] Added comments to AJAX callbacks.

PHPBB3-10271

phpBB/adm/style/ajax.js

@@ -1,7 +1,12 @@
 (function($) {  // Avoid conflicts with other libraries
 
 
-
+/**
+ * The following callbacks are  for reording forums in acp_forums. forum_down
+ * is triggered when a forum is moved down, and forum_up is triggered when
+ * a forum is moved up. It moves the row up or down, and deactivates /
+ * activates any up / down icons that require it (the ones at the top or bottom).
+ */
 phpbb.add_ajax_callback('forum_down', function(el) {
 	var tr = $(el).parents('tr');
 	if (tr.is(':first-child'))
@@ -32,7 +37,14 @@ phpbb.add_ajax_callback('forum_down', function(el) {
 		tr.next().find('.up').html('<a href="' + tr.data('up') + '"><img src="./images/icon_up.gif" alt="Move up" title="Move up" /></a>');
 		phpbb.ajaxify({selector: tr.next().find('.up').children('a')}, false, 'forum_up');
 	}
-}).add_ajax_callback('act_deact', function(el, res) {
+});
+
+/**
+ * This callback replaces activate links with deactivate links and vice versa.
+ * It does this by replacing the text, and replacing all instances of "activate"
+ * in the href with "deactivate", and vice versa.
+ */
+phpbb.add_ajax_callback('act_deact', function(el, res) {
 	$(el).text(res.text);
 	var new_href = $(el).attr('href');
 	if (new_href.indexOf('deactivate') !== -1)
@@ -44,7 +56,13 @@ phpbb.add_ajax_callback('forum_down', function(el) {
 		new_href = new_href.replace('activate', 'deactivate')
 	}
 	$(el).attr('href', new_href);
-}).add_ajax_callback('row_delete', function(el) {
+});
+
+/**
+ * The removes the parent row of the link or form that triggered the callback,
+ * and is good for stuff like the removal of forums.
+ */
+phpbb.add_ajax_callback('row_delete', function(el) {
 	var tr = $(el).parents('tr');
 	tr.remove();
 });

phpBB/assets/javascript/core.js

@@ -353,6 +353,11 @@ phpbb.add_ajax_callback = function(id, callback)
 }
 
 
+/**
+ * This callback alternates text - it replaces the current text with the text in
+ * the alt-text data attribute, and replaces the text in the attribute with the
+ * current text so that the process can be repeated.
+ */
 phpbb.add_ajax_callback('alt_text', function(el) {
 	var alt_text = $(el).data('alt-text');
 	$(el).data('alt-text', $(el).text());

phpBB/styles/prosilver/template/ajax.js

@@ -1,7 +1,7 @@
 (function($) {  // Avoid conflicts with other libraries
 
 
-
+//This callback finds the post from the delete link, and removes it.
 phpbb.add_ajax_callback('post_delete', function(el) {
 	if ($(this).data('refresh') === undefined)
 	{
@@ -10,18 +10,30 @@ phpbb.add_ajax_callback('post_delete', function(el) {
 			$(this).remove();
 		});
 	}
-}).add_ajax_callback('post_approve', function(el, res, act) {
+});
+
+// This callback removes the approve / disapprove div or link.
+phpbb.add_ajax_callback('post_approve', function(el, res, act) {
 	$(el).parents((act === 'approve') ? '.rules' : '.post').fadeOut(function() {
 		$(this).remove();
 	});
-}).add_ajax_callback('qr-submit', function(el) {
+});
+
+// This callback handles the removal of the quick reply form.
+phpbb.add_ajax_callback('qr-submit', function(el) {
 	$(el).parents('form').fadeOut(function() {
 		$(this).remove();
 	});
-}).add_ajax_callback('row_delete', function(el) {
+});
+
+// This removes the parent row of the link or form that fired the callback.
+phpbb.add_ajax_callback('row_delete', function(el) {
 	var tr = $(el).parents('tr');
 	tr.remove();
-}).add_ajax_callback('zebra', function(el, res) {
+});
+
+// This handles friend / foe additions removals.
+phpbb.add_ajax_callback('zebra', function(el, res) {
 	if (res.success) {
 		$('.zebra').html(res.MESSAGE_TEXT);
 		$($('.zebra').get(1)).remove();
@@ -37,6 +49,11 @@ $('[data-ajax]').each(function() {
 
 
 
+/**
+ * This AJAXifies the quick-mod tools. The reason it cannot be a standard
+ * callback / data attribute is that it requires exceptions - some of the options
+ * can be ajaxified, while others cannot.
+ */
 phpbb.ajaxify({
 	selector: '#quickmodform',
 	exception: function(el, act, data) {