Changeset 42426

Timestamp:

01/04/2018 02:36:13 PM (7 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(); });