Docs: Add wp-admin/js/media.js documentation.

Props jipmoors, jjcomack, diedeexterkate.
Fixes #41072.

Built from https://develop.svn.wordpress.org/trunk@40915


git-svn-id: http://core.svn.wordpress.org/trunk@40765 1a063a9b-81f0-0310-95a4-ce76da25c4cd

wp-admin/js/media.js

@@ -1,8 +1,33 @@
 /* global ajaxurl, attachMediaBoxL10n, _wpMediaGridSettings, showNotice */
 
+/**
+ * @summary Creates a dialog containing posts that can have a particular media attached to it.
+ *
+ * @since 2.7.0
+ *
+ * @global
+ * @namespace
+ *
+ * @requires jQuery
+ */
 var findPosts;
+
 ( function( $ ){
 	findPosts = {
+		/**
+		 * @summary Opens a dialog to attach media to a post.
+		 *
+		 * Adds an overlay prior to retrieving a list of posts to attach the media to.
+		 *
+		 * @since 2.7.0
+		 *
+		 * @memberOf findPosts
+		 *
+		 * @param {string} af_name The name of the affected element.
+		 * @param {string} af_val The value of the affected post element.
+		 *
+		 * @returns {boolean} Always returns false.
+		 */
 		open: function( af_name, af_val ) {
 			var overlay = $( '.ui-find-overlay' );
 
@@ -14,35 +39,67 @@ var findPosts;
 			overlay.show();
 
 			if ( af_name && af_val ) {
+				// #affected is a hidden input field in the dialog that keeps track of which media should be attached.
 				$( '#affected' ).attr( 'name', af_name ).val( af_val );
 			}
 
 			$( '#find-posts' ).show();
 
+			// Close the dialog when the escape key is pressed.
 			$('#find-posts-input').focus().keyup( function( event ){
 				if ( event.which == 27 ) {
 					findPosts.close();
-				} // close on Escape
+				}
 			});
 
-			// Pull some results up by default
+			// Retrieves a list of applicable posts for media attachment and shows them.
 			findPosts.send();
 
 			return false;
 		},
 
+		/**
+		 * @summary Clears the found posts lists before hiding the attach media dialog.
+		 *
+		 * @since 2.7.0
+		 *
+		 * @memberOf findPosts
+		 *
+		 * @returns {void}
+		 */
 		close: function() {
 			$('#find-posts-response').empty();
 			$('#find-posts').hide();
 			$( '.ui-find-overlay' ).hide();
 		},
 
+		/**
+		 * @summary Binds a click event listener to the overlay which closes the attach media dialog.
+		 *
+		 * @since 3.5.0
+		 *
+		 * @memberOf findPosts
+		 *
+		 * @returns {void}
+		 */
 		overlay: function() {
 			$( '.ui-find-overlay' ).on( 'click', function () {
 				findPosts.close();
 			});
 		},
 
+		/**
+		 * @summary Retrieves and displays posts based on the search term.
+		 *
+		 * Sends a post request to the admin_ajax.php, requesting posts based on the search term provided by the user.
+		 * Defaults to all posts if no search term is provided.
+		 *
+		 * @since 2.7.0
+		 *
+		 * @memberOf findPosts
+		 *
+		 * @returns {void}
+		 */
 		send: function() {
 			var post = {
 					ps: $( '#find-posts-input' ).val(),
@@ -53,6 +110,10 @@ var findPosts;
 
 			spinner.addClass( 'is-active' );
 
+			/**
+			 * Send a POST request to admin_ajax.php, hide the spinner and replace the list of posts with the response data.
+			 * If an error occurs, display it.
+			 */
 			$.ajax( ajaxurl, {
 				type: 'POST',
 				data: post,
@@ -71,10 +132,15 @@ var findPosts;
 		}
 	};
 
+	/**
+	 * @summary Initializes the file once the DOM is fully loaded and attaches events to the various form elements.
+	 *
+	 * @returns {void}
+	 */
 	$( document ).ready( function() {
 		var settings, $mediaGridWrap = $( '#wp-media-grid' );
 
-		// Open up a manage media frame into the grid.
+		// Opens a manage media frame into the grid.
 		if ( $mediaGridWrap.length && window.wp && window.wp.media ) {
 			settings = _wpMediaGridSettings;
 
@@ -85,19 +151,33 @@ var findPosts;
 			}).open();
 		}
 
+		// Prevents form submission if no post has been selected.
 		$( '#find-posts-submit' ).click( function( event ) {
 			if ( ! $( '#find-posts-response input[type="radio"]:checked' ).length )
 				event.preventDefault();
 		});
+
+		// Submits the search query when hitting the enter key in the search input.
 		$( '#find-posts .find-box-search :input' ).keypress( function( event ) {
 			if ( 13 == event.which ) {
 				findPosts.send();
 				return false;
 			}
 		});
+
+		// Binds the click event to the search button.
 		$( '#find-posts-search' ).click( findPosts.send );
+
+		// Binds the close dialog click event.
 		$( '#find-posts-close' ).click( findPosts.close );
+
+		// Binds the bulk action events to the submit buttons.
 		$( '#doaction, #doaction2' ).click( function( event ) {
+
+			/*
+			 * Retrieves all select elements for bulk actions that have a name starting with `action`
+			 * and handle its action based on its value.
+			 */
 			$( 'select[name^="action"]' ).each( function() {
 				var optionValue = $( this ).val();
 
@@ -112,7 +192,11 @@ var findPosts;
 			});
 		});
 
-		// Enable whole row to be clicked
+		/**
+		 * @summary Enables clicking on the entire table row.
+		 *
+		 * @returns {void}
+		 */
 		$( '.find-box-inside' ).on( 'click', 'tr', function() {
 			$( this ).find( '.found-radio input' ).prop( 'checked', true );
 		});

wp-includes/version.php

@@ -4,7 +4,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '4.9-alpha-40914';
+$wp_version = '4.9-alpha-40915';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.