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

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


git-svn-id: https://develop.svn.wordpress.org/trunk@42426 602fd350-edb4-49c9-b593-d223f7449a82

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

@@ -1,13 +1,38 @@
 /* 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,
 		hasTinymce = typeof tinymce !== 'undefined',
 		hasQuicktags = typeof QTags !== 'undefined';
 
+	// If no active editor is set, try to set it.
 	if ( ! wpActiveEditor ) {
 		if ( hasTinymce && tinymce.activeEditor ) {
 			editor = tinymce.activeEditor;
@@ -19,23 +44,38 @@ send_to_editor = function( html ) {
 		editor = tinymce.get( wpActiveEditor );
 	}
 
+	// 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 ) {}
 	}
 };
 
-// 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'),
 			width = $(window).width(),
@@ -55,6 +95,11 @@ var tb_position;
 				tbWindow.css({'top': 20 + adminbar_height + 'px', 'margin-top': '0'});
 		}
 
+		/**
+		 * 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');
 			if ( ! href ) return;
@@ -64,6 +109,7 @@ var tb_position;
 		});
 	};
 
+	// Add handler to recalculates the ThickBox position when the window is resized.
 	$(window).resize(function(){ tb_position(); });
 
 })(jQuery);