Changeset 42426

Timestamp:

01/04/2018 02:36:13 PM (9 years ago)

Author:

atimmer

Message:

Docs: Improve JSDoc for js/media-upload.js.

Props terwdan, diedeexterkate, andizer, ireneyoast.
Fixes #42956.

File:

• trunk/src/wp-admin/js/media-upload.js (modified) (6 diffs)

trunk/src/wp-admin/js/media-upload.js

@@ -1 +1 @@
 /* global tinymce, QTags */
-// send html to the post editor
+
+/**
+ * Contains global functions for the media upload within the post edit screen.
+ *
+ * Updates the ThickBox anchor href and the ThickBox's own properties in order
+ * to set the size and position on every resize event. Also adds a function to
+ * send HTML or text to the currently active editor.
+ *
+ * @file
+ * @since 2.5.0
+ *
+ * @requires jQuery
+ */
 
 var wpActiveEditor, send_to_editor;
 
+/**
+ * Sends the HTML passed in the parameters to TinyMCE.
+ *
+ * @since 2.5.0
+ *
+ * @global
+ *
+ * @param {string} html The HTML to be sent to the editor.
+ * @returns {void|boolean} Returns false when both TinyMCE and QTags instances
+ *                         are unavailable. This means that the HTML was not
+ *                         sent to the editor.
+ */
 send_to_editor = function( html ) {
         var editor,
@@ -9 +33 @@
                 hasQuicktags = typeof QTags !== 'undefined';
 
+        // If no active editor is set, try to set it.
         if ( ! wpActiveEditor ) {
                 if ( hasTinymce && tinymce.activeEditor ) {
@@ -20 +45 @@
         }
 
+        // If the editor is set and not hidden, insert the HTML into the content of the
+        // editor.
         if ( editor && ! editor.isHidden() ) {
                 editor.execCommand( 'mceInsertContent', false, html );
         } else if ( hasQuicktags ) {
+                // If quick tags are available, insert the HTML into its content.
                 QTags.insertContent( html );
         } else {
+                // If neither the TinyMCE editor and the quick tags are available, add the HTML
+                // to the current active editor.
                 document.getElementById( wpActiveEditor ).value += html;
         }
 
-        // If the old thickbox remove function exists, call it
+        // If the old thickbox remove function exists, call it.
         if ( window.tb_remove ) {
                 try { window.tb_remove(); } catch( e ) {}
@@ -34 +64 @@
 };
 
-// thickbox settings
 var tb_position;
 (function($) {
+        /**
+         * Recalculates and applies the new ThickBox position based on the current
+         * window size.
+         *
+         * @since 2.6.0
+         *
+         * @global
+         *
+         * @returns {Object[]} Array containing jQuery objects for all the found
+         *                     ThickBox anchors.
+         */
         tb_position = function() {
                 var tbWindow = $('#TB_window'),
@@ -56 +96 @@
                 }
 
+                /**
+                 * Recalculates the new height and width for all links with a ThickBox class.
+                 *
+                 * @since 2.6.0
+                 */
                 return $('a.thickbox').each( function() {
                         var href = $(this).attr('href');
@@ -65 +110 @@
         };
 
+        // Add handler to recalculates the ThickBox position when the window is resized.
         $(window).resize(function(){ tb_position(); });