Changeset 42963

Timestamp:

04/06/2018 07:46:14 AM (6 years ago)

Author:

atimmer

Message:

Docs: Improve JSDoc for wp-admin/js/tags-box.js.

Props carolinegeven, andizer, ireneyoast, herregroen, jjcomack.
Fixes #43499.

File:

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

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

@@ -7 +7 @@
     var tagDelimiter = ( window.tagsSuggestL10n && window.tagsSuggestL10n.tagDelimiter ) || ',';
 
-    // Return an array with any duplicate, whitespace or empty values removed
+    /**
+     * Filters unique items and returns a new array.
+     *
+     * Filters all items from an array into a new array containing only the unique
+     * items. This also excludes whitespace or empty values.
+     *
+     * @since 2.8.0
+     *
+     * @global
+     *
+     * @param {Array} array The array to filter through.
+     *
+     * @return {Array} A new array containing only the unique items.
+     */
     array_unique_noempty = function( array ) {
         var out = [];
 
+        // Trim the values and ensure they are unique.
         $.each( array, function( key, val ) {
             val = $.trim( val );
@@ -22 +36 @@
     };
 
+    /**
+     * The TagBox object.
+     *
+     * Contains functions to create and manage tags that can be associated with a
+     * post.
+     *
+     * @since 2.9.0
+     *
+     * @global
+     */
     tagBox = {
+        /**
+         * Cleans up tags by removing redundant characters.
+         *
+         * @since 2.9.0
+         * @memberOf tagBox
+         *
+         * @param {string} tags Comma separated tags that need to be cleaned up.
+         *
+         * @return {string} The cleaned up tags.
+         */
         clean : function( tags ) {
             if ( ',' !== tagDelimiter ) {
@@ -37 +71 @@
         },
 
+        /**
+         * Parses tags and makes them editable.
+         *
+         * @since 2.9.0
+         * @memberOf tagBox
+         *
+         * @param {Object} el The tag element to retrieve the ID from.
+         *
+         * @return {boolean} Always returns false.
+         */
         parseTags : function(el) {
             var id = el.id,
@@ -47 +91 @@
             delete current_tags[num];
 
+            // Sanitize the current tags and push them as if they're new tags.
             $.each( current_tags, function( key, val ) {
                 val = $.trim( val );
@@ -60 +105 @@
         },
 
+        /**
+         * Creates clickable links, buttons and fields for adding or editing tags.
+         *
+         * @since 2.9.0
+         * @memberOf tagBox
+         *
+         * @param {Object} el The container HTML element.
+         *
+         * @return {void}
+         */
         quickClicks : function( el ) {
             var thetags = $('.the-tags', el),
@@ -74 +129 @@
             tagchecklist.empty();
 
+            /**
+             * Creates a delete button if tag editing is enabled, before adding it to the tag list.
+             *
+             * @since 2.5.0
+             * @memberOf tagBox
+             *
+             * @param {string} key The index of the current tag.
+             * @param {string} val The value of the current tag.
+             *
+             * @return {void}
+             */
             $.each( current_tags, function( key, val ) {
                 var listItem, xbutton;
@@ -96 +162 @@
                         '</button>' );
 
+                    /**
+                     * Handles the click and keypress event of the tag remove button.
+                     *
+                     * Makes sure the focus ends up in the tag input field when using
+                     * the keyboard to delete the tag.
+                     *
+                     * @since 4.2.0
+                     *
+                     * @param {Event} e The click or keypress event to handle.
+                     *
+                     * @return {void}
+                     */
                     xbutton.on( 'click keypress', function( e ) {
                         // On click or when using the Enter/Spacebar keys.
@@ -119 +197 @@
                 tagchecklist.append( listItem );
             });
+
             // The buttons list is built now, give feedback to screen reader users.
             tagBox.screenReadersMessage();
         },
 
+        /**
+         * Adds a new tag.
+         *
+         * Also ensures that the quick links are properly generated.
+         *
+         * @since 2.9.0
+         * @memberOf tagBox
+         *
+         * @param {Object} el The container HTML element.
+         * @param {Object|boolean} a When this is an HTML element the text of that
+         *                           element will be used for the new tag.
+         * @param {number|boolean} f If this value is not passed then the tag input
+         *                           field is focused.
+         *
+         * @return {boolean} Always returns false.
+         */
         flushTags : function( el, a, f ) {
             var tagsval, newtags, text,
@@ -159 +254 @@
         },
 
+        /**
+         * Retrieves the available tags and creates a tagcloud.
+         *
+         * Retrieves the available tags from the database and creates an interactive
+         * tagcloud. Clicking a tag will add it.
+         *
+         * @since 2.9.0
+         * @memberOf tagBox
+         *
+         * @param {string} id The ID to extract the taxonomy from.
+         *
+         * @return {void}
+         */
         get : function( id ) {
             var tax = id.substr( id.indexOf('-') + 1 );
 
+            /**
+             * Puts a received tag cloud into a DOM element.
+             *
+             * The tag cloud HTML is generated on the server.
+             *
+             * @since 2.9.0
+             *
+             * @param {number|string} r The response message from the AJAX call.
+             * @param {string} stat The status of the AJAX request.
+             *
+             * @return {void}
+             */
             $.post( ajaxurl, { 'action': 'get-tagcloud', 'tax': tax }, function( r, stat ) {
                 if ( 0 === r || 'success' != stat ) {
@@ -169 +289 @@
                 r = $( '<div id="tagcloud-' + tax + '" class="the-tagcloud">' + r + '</div>' );
 
+                /**
+                 * Adds a new tag when a tag in the tagcloud is clicked.
+                 *
+                 * @since 2.9.0
+                 *
+                 * @return {boolean} Returns false to prevent the default action.
+                 */
                 $( 'a', r ).click( function() {
                     tagBox.userAction = 'add';
@@ -187 +314 @@
 
         /**
-         * Dispatch an audible message to screen readers.
+         * Dispatches an audible message to screen readers.
+         *
+         * This will inform the user when a tag has been added or removed.
          *
          * @since 4.7.0
+         *
+         * @return {void}
          */
         screenReadersMessage: function() {
@@ -210 +341 @@
         },
 
+        /**
+         * Initializes the tags box by setting up the links, buttons. Sets up event
+         * handling.
+         *
+         * This includes handling of pressing the enter key in the input field and the
+         * retrieval of tag suggestions.
+         *
+         * @since 2.9.0
+         * @memberOf tagBox
+         *
+         * @return {void}
+         */
         init : function() {
             var ajaxtag = $('div.ajaxtag');
@@ -222 +365 @@
             });
 
+            /**
+             * Handles pressing enter on the new tag input field.
+             *
+             * Prevents submitting the post edit form.
+             *
+             * @since 2.9.0
+             *
+             * @param {Event} event The keypress event that occurred.
+             *
+             * @return {void}
+             */
             $( 'input.newtag', ajaxtag ).keypress( function( event ) {
                 if ( 13 == event.which ) {
@@ -238 +392 @@
             });
 
-            // save tags on post save/publish
+            /**
+             * Before a post is saved the value currently in the new tag input field will be
+             * added as a tag.
+             *
+             * @since 2.9.0
+             *
+             * @return {void}
+             */
             $('#post').submit(function(){
                 $('div.tagsdiv').each( function() {
@@ -245 +406 @@
             });
 
-            // Fetch and toggle the Tag cloud.
+            /**
+             * Handles clicking on the tag cloud link.
+             *
+             * Makes sure the ARIA attributes are set correctly.
+             *
+             * @since 2.9.0
+             *
+             * @return {void}
+             */
             $('.tagcloud-link').click(function(){
                 // On the first click, fetch the tag cloud and insert it in the DOM.