Changeset 41311

Timestamp:

08/24/2017 05:51:19 PM (8 years ago)

Author:

wonderboymusic

Message:

Docs: improve JS docs for tags.js

Props atimmer, jipmoors.
Fixes #41069.

File:

• trunk/src/wp-admin/js/tags.js (modified) (5 diffs)

trunk/src/wp-admin/js/tags.js

@@ -1 +1 @@
 /* global ajaxurl, wpAjax, tagsl10n, showNotice, validateForm */
+/**
+ * Contains logic for both adding and deleting tags. For deleting tags it makes a request
+ * to the server to delete the tag. For adding tags it makes a request to the server to
+ * add the tag.
+ *
+ * @summary Contains logic for deleting and adding tags
+ */
 
 jQuery(document).ready(function($) {
 
+    /**
+     * @summary Adds an event handler to the delete term link on the term overview page.
+     *
+     * Adds an event handler to the delete term link on the term overview page.
+     * Cancels default event handling and event bubbling.
+     *
+     * @since 2.8.0
+     *
+     * @returns boolean Always returns false to cancel the default event handling.
+     */
     $( '#the-list' ).on( 'click', '.delete-tag', function() {
         var t = $(this), tr = t.parents('tr'), r = true, data;
+
         if ( 'undefined' != showNotice )
             r = showNotice.warn();
+
         if ( r ) {
             data = t.attr('href').replace(/[^?]*\?/, '').replace(/action=delete/, 'action=delete-tag');
+
+            /**
+             * @summary Makes a request to the server to delete the term that
+             * corresponds to the delete term button.
+             *
+             * @param {string} r The response from the server.
+             *
+             * @returns {void}
+             */
             $.post(ajaxurl, data, function(r){
                 if ( '1' == r ) {
                     $('#ajax-response').empty();
                     tr.fadeOut('normal', function(){ tr.remove(); });
-                    // Remove the term from the parent box and tag cloud
+
+                    /**
+                     * @summary Remove the term from the parent box and the tag cloud
+                     *
+                     * `data.match(/tag_ID=(\d+)/)[1]` matches the term id from the data variable.
+                     * This term id is then used to select the relevant HTML elements:
+                     * The parent box and the tag cloud.
+                     */
                     $('select#parent option[value="' + data.match(/tag_ID=(\d+)/)[1] + '"]').remove();
                     $('a.tag-link-' + data.match(/tag_ID=(\d+)/)[1]).remove();
+
                 } else if ( '-1' == r ) {
                     $('#ajax-response').empty().append('<div class="error"><p>' + tagsl10n.noPerm + '</p></div>');
                     tr.children().css('backgroundColor', '');
+
                 } else {
                     $('#ajax-response').empty().append('<div class="error"><p>' + tagsl10n.broken + '</p></div>');
@@ -24 +61 @@
                 }
             });
+
             tr.children().css('backgroundColor', '#f33');
         }
+
         return false;
     });
 
+    /**
+     * Adds a deletion confirmation when removing a tag.
+     *
+     * @since 4.8.0
+     *
+     * @returns {void}
+     */
     $( '#edittag' ).on( 'click', '.delete', function( e ) {
         if ( 'undefined' === typeof showNotice ) {
@@ -34 +80 @@
         }
 
+        // Confirms the deletion, a negative response means the deletion must not be executed.
         var response = showNotice.warn();
         if ( ! response ) {
@@ -40 +87 @@
     });
 
+    /**
+     * @summary Adds an event handler tot he form submit on the term overview page.
+     *
+     * Cancels default event handling and event bubbling.
+     *
+     * @since 2.8.0
+     *
+     * @returns boolean Always returns false to cancel the default event handling.
+     */
     $('#submit').click(function(){
         var form = $(this).parents('form');
@@ -46 +102 @@
             return false;
 
+        /**
+         * Does a request to the server to add a new term to the database
+         *
+         * @param {string} r The response from the server.
+         *
+         * @returns {void}
+         */
         $.post(ajaxurl, $('#addtag').serialize(), function(r){
             var res, parent, term, indent, i;