Docs: JSDoc improvements for namespaces.

Improve JS parsing of our inline JSDocs by introducing `@namespace`, `@lends` and `@memberOf`. Helps set the way for showing our JavaScript documentation on developer.wordpress.org, see https://meta.trac.wordpress.org/ticket/3063.

* Define all used namespaces using @namespace.
* Correctly specify in which namespace each class is using @memberOf.
* Define each usage of the extend function as a prototype assignment using @lends.
* Some comment blocks were moved to correct the parsing of certain definitions. 

Props herregroen, atimmer, netweb, SergeyBiryukov.  
Fixes #41682.

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


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

wp-includes/js/api-request.js

@@ -8,7 +8,6 @@
  * - Sends the REST API nonce as a request header.
  * - Allows specifying only an endpoint namespace/path instead of a full URL.
  *
- * @namespace wp.apiRequest
  * @since     4.9.0
  */
 
@@ -82,6 +81,7 @@
 
 	apiRequest.transport = $.ajax;
 
+	/** @namespace wp */
 	window.wp = window.wp || {};
 	window.wp.apiRequest = apiRequest;
 } )( jQuery );

wp-includes/js/autosave.js

@@ -850,6 +850,7 @@ window.autosave = function() {
 		};
 	}
 
+	/** @namespace wp */
 	window.wp = window.wp || {};
 	window.wp.autosave = autosave();
 

wp-includes/js/customize-base.js

@@ -1,3 +1,4 @@
+/** @namespace wp */
 window.wp = window.wp || {};
 
 (function( exports, $ ){
@@ -165,9 +166,12 @@ window.wp = window.wp || {};
 	/**
 	 * Observable values that support two-way binding.
 	 *
+	 * @memberOf wp.customize
+	 * @alias wp.customize.Value
+	 *
 	 * @constructor
 	 */
-	api.Value = api.Class.extend({
+	api.Value = api.Class.extend(/** @lends wp.customize.Value.prototype */{
 		/**
 		 * @param {mixed}  initial The initial value.
 		 * @param {object} options
@@ -304,11 +308,14 @@ window.wp = window.wp || {};
 	/**
 	 * A collection of observable values.
 	 *
+	 * @memberOf wp.customize
+	 * @alias wp.customize.Values
+	 *
 	 * @constructor
 	 * @augments wp.customize.Class
 	 * @mixes wp.customize.Events
 	 */
-	api.Values = api.Class.extend({
+	api.Values = api.Class.extend(/** @lends wp.customize.Values.prototype */{
 
 		/**
 		 * The default constructor for items of the collection.
@@ -520,11 +527,14 @@ window.wp = window.wp || {};
 	 *
 	 * Handles inputs, selects, and textareas by default.
 	 *
+	 * @memberOf wp.customize
+	 * @alias wp.customize.Element
+	 *
 	 * @constructor
 	 * @augments wp.customize.Value
 	 * @augments wp.customize.Class
 	 */
-	api.Element = api.Value.extend({
+	api.Element = api.Value.extend(/** @lends wp.customize.Element */{
 		initialize: function( element, options ) {
 			var self = this,
 				synchronizer = api.Element.synchronizer.html,
@@ -617,11 +627,14 @@ window.wp = window.wp || {};
 	/**
 	 * A communicator for sending data from one window to another over postMessage.
 	 *
+	 * @memberOf wp.customize
+	 * @alias wp.customize.Messenger
+	 *
 	 * @constructor
 	 * @augments wp.customize.Class
 	 * @mixes wp.customize.Events
 	 */
-	api.Messenger = api.Class.extend({
+	api.Messenger = api.Class.extend(/** @lends wp.customize.Messenger.prototype */{
 		/**
 		 * Create a new Value.
 		 *
@@ -765,6 +778,9 @@ window.wp = window.wp || {};
 	 * @augments wp.customize.Class
 	 * @since 4.6.0
 	 *
+	 * @memberOf wp.customize
+	 * @alias wp.customize.Notification
+	 *
 	 * @param {string}  code - The error code.
 	 * @param {object}  params - Params.
 	 * @param {string}  params.message=null - The error message.
@@ -773,7 +789,7 @@ window.wp = window.wp || {};
 	 * @param {string}  [params.setting=null] - The setting ID that the notification is related to.
 	 * @param {*}       [params.data=null] - Any additional data.
 	 */
-	api.Notification = api.Class.extend({
+	api.Notification = api.Class.extend(/** @lends wp.customize.Notification.prototype */{
 		initialize: function( code, params ) {
 			var _params;
 			this.code = code;
@@ -798,6 +814,8 @@ window.wp = window.wp || {};
 	/**
 	 * Get all customize settings.
 	 *
+	 * @memberOf wp.customize
+	 *
 	 * @return {object}
 	 */
 	api.get = function() {
@@ -812,6 +830,8 @@ window.wp = window.wp || {};
 
 	/**
 	 * Utility function namespace
+	 *
+	 * @namespace wp.customize.utils
 	 */
 	api.utils = {};
 
@@ -820,6 +840,7 @@ window.wp = window.wp || {};
 	 *
 	 * @since 4.7.0
 	 * @access public
+	 * @memberOf wp.customize.utils
 	 *
 	 * @param {string} queryString Query string.
 	 * @returns {object} Parsed query string.
@@ -844,6 +865,10 @@ window.wp = window.wp || {};
 		return queryParams;
 	};
 
-	// Expose the API publicly on window.wp.customize
+	/**
+	 * Expose the API publicly on window.wp.customize
+	 *
+	 * @namespace wp.customize
+	 */
 	exports.customize = api;
 })( wp, jQuery );

wp-includes/js/customize-loader.js

@@ -1,7 +1,9 @@
 /* global _wpCustomizeLoaderSettings, confirm */
-/*
+/**
  * Expose a public API that allows the customizer to be
  * loaded on any page.
+ *
+ * @namespace wp
  */
 window.wp = window.wp || {};
 
@@ -22,9 +24,12 @@ window.wp = window.wp || {};
 	 *
 	 *     e.g. <a class="load-customize" href="<?php echo wp_customize_url(); ?>">Open Customizer</a>
 	 *
+	 * @memberOf wp.customize
+	 *
+	 * @class
 	 * @augments wp.customize.Events
 	 */
-	Loader = $.extend( {}, api.Events, {
+	Loader = $.extend( {}, api.Events,/** @lends wp.customize.Loader.prototype */{
 		/**
 		 * Setup the Loader; triggered on document#ready.
 		 */

wp-includes/js/customize-models.js

@@ -1,6 +1,7 @@
 /* global _wpCustomizeHeader */
 (function( $, wp ) {
 	var api = wp.customize;
+	/** @namespace wp.customize.HeaderTool */
 	api.HeaderTool = {};
 
 
@@ -13,10 +14,13 @@
 	 * These calls are made regardless of whether the user actually saves new
 	 * Customizer settings.
 	 *
+	 * @memberOf wp.customize.HeaderTool
+	 * @alias wp.customize.HeaderTool.ImageModel
+	 *
 	 * @constructor
 	 * @augments Backbone.Model
 	 */
-	api.HeaderTool.ImageModel = Backbone.Model.extend({
+	api.HeaderTool.ImageModel = Backbone.Model.extend(/** @lends wp.customize.HeaderTool.ImageModel.prototype */{
 		defaults: function() {
 			return {
 				header: {
@@ -125,6 +129,9 @@
 	/**
 	 * wp.customize.HeaderTool.ChoiceList
 	 *
+	 * @memberOf wp.customize.HeaderTool
+	 * @alias wp.customize.HeaderTool.ChoiceList
+	 *
 	 * @constructor
 	 * @augments Backbone.Collection
 	 */
@@ -232,6 +239,9 @@
 	/**
 	 * wp.customize.HeaderTool.DefaultsList
 	 *
+	 * @memberOf wp.customize.HeaderTool
+	 * @alias wp.customize.HeaderTool.DefaultsList
+	 *
 	 * @constructor
 	 * @augments wp.customize.HeaderTool.ChoiceList
 	 * @augments Backbone.Collection

wp-includes/js/customize-preview-nav-menus.js

@@ -1,4 +1,6 @@
 /* global _wpCustomizePreviewNavMenusExports */
+
+/** @namespace wp.customize.navMenusPreview */
 wp.customize.navMenusPreview = wp.customize.MenusCustomizerPreview = ( function( $, _, wp, api ) {
 	'use strict';
 
@@ -72,11 +74,14 @@ wp.customize.navMenusPreview = wp.customize.MenusCustomizerPreview = ( function(
 		/**
 		 * Partial representing an invocation of wp_nav_menu().
 		 *
+		 * @memberOf wp.customize.navMenusPreview
+		 * @alias wp.customize.navMenusPreview.NavMenuInstancePartial
+		 *
 		 * @class
 		 * @augments wp.customize.selectiveRefresh.Partial
 		 * @since 4.5.0
 		 */
-		self.NavMenuInstancePartial = api.selectiveRefresh.Partial.extend({
+		self.NavMenuInstancePartial = api.selectiveRefresh.Partial.extend(/** @lends wp.customize.navMenusPreview.NavMenuInstancePartial.prototype */{
 
 			/**
 			 * Constructor.

wp-includes/js/customize-preview-widgets.js

@@ -1,4 +1,6 @@
 /* global _wpWidgetCustomizerPreviewSettings */
+
+/** @namespace wp.customize.widgetsPreview */
 wp.customize.widgetsPreview = wp.customize.WidgetCustomizerPreview = (function( $, _, wp, api ) {
 
 	var self;
@@ -42,11 +44,14 @@ wp.customize.widgetsPreview = wp.customize.WidgetCustomizerPreview = (function(
 	/**
 	 * Partial representing a widget instance.
 	 *
+	 * @memberOf wp.customize.widgetsPreview
+	 * @alias wp.customize.widgetsPreview.WidgetPartial
+	 *
 	 * @class
 	 * @augments wp.customize.selectiveRefresh.Partial
 	 * @since 4.5.0
 	 */
-	self.WidgetPartial = api.selectiveRefresh.Partial.extend({
+	self.WidgetPartial = api.selectiveRefresh.Partial.extend(/** @lends wp.customize.widgetsPreview.WidgetPartial.prototype */{
 
 		/**
 		 * Constructor.
@@ -112,11 +117,14 @@ wp.customize.widgetsPreview = wp.customize.WidgetCustomizerPreview = (function(
 	/**
 	 * Partial representing a widget area.
 	 *
+	 * @memberOf wp.customize.widgetsPreview
+	 * @alias wp.customize.widgetsPreview.SidebarPartial
+	 *
 	 * @class
 	 * @augments wp.customize.selectiveRefresh.Partial
 	 * @since 4.5.0
 	 */
-	self.SidebarPartial = api.selectiveRefresh.Partial.extend({
+	self.SidebarPartial = api.selectiveRefresh.Partial.extend(/** @lends wp.customize.widgetsPreview.SidebarPartial.prototype */{
 
 		/**
 		 * Constructor.
@@ -510,6 +518,8 @@ wp.customize.widgetsPreview = wp.customize.WidgetCustomizerPreview = (function(
 	/**
 	 * Calculate the selector for the sidebar's widgets based on the registered sidebar's info.
 	 *
+	 * @memberOf wp.customize.widgetsPreview
+	 *
 	 * @since 3.9.0
 	 */
 	self.buildWidgetSelectors = function() {
@@ -548,6 +558,8 @@ wp.customize.widgetsPreview = wp.customize.WidgetCustomizerPreview = (function(
 	/**
 	 * Highlight the widget on widget updates or widget control mouse overs.
 	 *
+	 * @memberOf wp.customize.widgetsPreview
+	 *
 	 * @since 3.9.0
 	 * @param  {string} widgetId ID of the widget.
 	 */
@@ -567,6 +579,8 @@ wp.customize.widgetsPreview = wp.customize.WidgetCustomizerPreview = (function(
 	 * Show a title and highlight widgets on hover. On shift+clicking
 	 * focus the widget control.
 	 *
+	 * @memberOf wp.customize.widgetsPreview
+	 *
 	 * @since 3.9.0
 	 */
 	self.highlightControls = function() {
@@ -598,6 +612,8 @@ wp.customize.widgetsPreview = wp.customize.WidgetCustomizerPreview = (function(
 	/**
 	 * Parse a widget ID.
 	 *
+	 * @memberOf wp.customize.widgetsPreview
+	 *
 	 * @since 4.5.0
 	 *
 	 * @param {string} widgetId Widget ID.
@@ -623,6 +639,8 @@ wp.customize.widgetsPreview = wp.customize.WidgetCustomizerPreview = (function(
 	/**
 	 * Parse a widget setting ID.
 	 *
+	 * @memberOf wp.customize.widgetsPreview
+	 *
 	 * @since 4.5.0
 	 *
 	 * @param {string} settingId Widget setting ID.
@@ -648,6 +666,8 @@ wp.customize.widgetsPreview = wp.customize.WidgetCustomizerPreview = (function(
 	/**
 	 * Convert a widget ID into a Customizer setting ID.
 	 *
+	 * @memberOf wp.customize.widgetsPreview
+	 *
 	 * @since 4.5.0
 	 *
 	 * @param {string} widgetId Widget ID.

wp-includes/js/customize-preview.js

@@ -87,12 +87,15 @@
 	};
 
 	/**
+	 * @memberOf wp.customize
+	 * @alias wp.customize.Preview
+	 *
 	 * @constructor
 	 * @augments wp.customize.Messenger
 	 * @augments wp.customize.Class
 	 * @mixes wp.customize.Events
 	 */
-	api.Preview = api.Messenger.extend({
+	api.Preview = api.Messenger.extend(/** @lends wp.customize.Preview.prototype */{
 		/**
 		 * @param {object} params  - Parameters to configure the messenger.
 		 * @param {object} options - Extend any instance parameter or method with this object.

wp-includes/js/customize-selective-refresh.js

@@ -1,5 +1,6 @@
 /* global jQuery, JSON, _customizePartialRefreshExports, console */
 
+/** @namespace wp.customize.selectiveRefresh */
 wp.customize.selectiveRefresh = ( function( $, api ) {
 	'use strict';
 	var self, Partial, Placement;
@@ -24,6 +25,8 @@ wp.customize.selectiveRefresh = ( function( $, api ) {
 	 *
 	 * A partial provides a rendering of one or more settings according to a template.
 	 *
+	 * @memberOf wp.customize.selectiveRefresh
+	 *
 	 * @see PHP class WP_Customize_Partial.
 	 *
 	 * @class
@@ -39,7 +42,7 @@ wp.customize.selectiveRefresh = ( function( $, api ) {
 	 * @param {string} options.params.primarySetting   The ID for the primary setting the partial renders.
 	 * @param {bool}   options.params.fallbackRefresh  Whether to refresh the entire preview in case of a partial refresh failure.
 	 */
-	Partial = self.Partial = api.Class.extend({
+	Partial = self.Partial = api.Class.extend(/** @lends wp.customize.SelectiveRefresh.Partial.prototype */{
 
 		id: null,
 
@@ -508,11 +511,13 @@ wp.customize.selectiveRefresh = ( function( $, api ) {
 	 * It also may have information in relation to how a placement may have just changed.
 	 * The placement is conceptually similar to a DOM Range or MutationRecord.
 	 *
-	 * @class
+	 * @memberOf wp.customize.selectiveRefresh
+	 *
+	 * @class Placement
 	 * @augments wp.customize.Class
 	 * @since 4.5.0
 	 */
-	self.Placement = Placement = api.Class.extend({
+	self.Placement = Placement = api.Class.extend(/** @lends wp.customize.selectiveRefresh.prototype */{
 
 		/**
 		 * The partial with which the container is associated.

wp-includes/js/customize-views.js

@@ -11,10 +11,13 @@
 	 *
 	 * Instantiate with model wp.customize.HeaderTool.currentHeader.
 	 *
+	 * @memberOf wp.customize.HeaderTool
+	 * @alias wp.customize.HeaderTool.CurrentView
+	 *
 	 * @constructor
 	 * @augments wp.Backbone.View
 	 */
-	api.HeaderTool.CurrentView = wp.Backbone.View.extend({
+	api.HeaderTool.CurrentView = wp.Backbone.View.extend(/** @lends wp.customize.HeaderTool.CurrentView.prototype */{
 		template: wp.template('header-current'),
 
 		initialize: function() {
@@ -50,10 +53,13 @@
 	 * Manually changes model wp.customize.HeaderTool.currentHeader via the
 	 * `select` method.
 	 *
+	 * @memberOf wp.customize.HeaderTool
+	 * @alias wp.customize.HeaderTool.ChoiceView
+	 *
 	 * @constructor
 	 * @augments wp.Backbone.View
 	 */
-	api.HeaderTool.ChoiceView = wp.Backbone.View.extend({
+	api.HeaderTool.ChoiceView = wp.Backbone.View.extend(/** @lends wp.customize.HeaderTool.ChoiceView.prototype */{
 		template: wp.template('header-choice'),
 
 		className: 'header-view',
@@ -125,10 +131,13 @@
 	 *
 	 * Takes a wp.customize.HeaderTool.ChoiceList.
 	 *
+	 * @memberOf wp.customize.HeaderTool
+	 * @alias wp.customize.HeaderTool.ChoiceListView
+	 *
 	 * @constructor
 	 * @augments wp.Backbone.View
 	 */
-	api.HeaderTool.ChoiceListView = wp.Backbone.View.extend({
+	api.HeaderTool.ChoiceListView = wp.Backbone.View.extend(/** @lends wp.customize.HeaderTool.ChoiceListView.prototype */{
 		initialize: function() {
 			this.listenTo(this.collection, 'add', this.addOne);
 			this.listenTo(this.collection, 'remove', this.render);
@@ -168,10 +177,13 @@
 	 * Aggregates wp.customize.HeaderTool.ChoiceList collections (or any
 	 * Backbone object, really) and acts as a bus to feed them events.
 	 *
+	 * @memberOf wp.customize.HeaderTool
+	 * @alias wp.customize.HeaderTool.CombinedList
+	 *
 	 * @constructor
 	 * @augments wp.Backbone.View
 	 */
-	api.HeaderTool.CombinedList = wp.Backbone.View.extend({
+	api.HeaderTool.CombinedList = wp.Backbone.View.extend(/** @lends wp.customize.HeaderTool.CombinedList.prototype */{
 		initialize: function(collections) {
 			this.collections = collections;
 			this.on('all', this.propagate, this);

wp-includes/js/heartbeat.js

@@ -742,7 +742,11 @@
 		};
 	};
 
-	// Ensure the global `wp` object exists.
+	/**
+	 * Ensure the global `wp` object exists.
+	 *
+	 * @namespace wp
+	 */
 	window.wp = window.wp || {};
 	window.wp.heartbeat = new Heartbeat();
 

wp-includes/js/mce-view.js

@@ -280,7 +280,7 @@
 
 	wp.mce.View.extend = Backbone.View.extend;
 
-	_.extend( wp.mce.View.prototype, {
+	_.extend( wp.mce.View.prototype, /** @lends wp.mce.View.prototype */{
 
 		/**
 		 * The content.

wp-includes/js/media-audiovideo.js

@@ -279,20 +279,22 @@ media.view.AudioDetails = require( './views/audio-details.js' );
 media.view.VideoDetails = require( './views/video-details.js' );
 
 },{"./controllers/audio-details.js":2,"./controllers/video-details.js":3,"./models/post-media.js":4,"./views/audio-details.js":5,"./views/frame/audio-details.js":6,"./views/frame/media-details.js":7,"./views/frame/video-details.js":8,"./views/media-details.js":9,"./views/video-details.js":10}],2:[function(require,module,exports){
+var State = wp.media.controller.State,
+	l10n = wp.media.view.l10n,
+	AudioDetails;
+
 /**
  * wp.media.controller.AudioDetails
  *
  * The controller for the Audio Details state
  *
+ * @memberOf wp.media.controller
+ *
  * @class
  * @augments wp.media.controller.State
  * @augments Backbone.Model
  */
-var State = wp.media.controller.State,
+AudioDetails = State.extend(/** @lends wp.media.controller.AudioDetails.prototype */{
-	l10n = wp.media.view.l10n,
-	AudioDetails;
-
-AudioDetails = State.extend({
 	defaults: {
 		id: 'audio-details',
 		toolbar: 'audio-details',
@@ -317,6 +319,8 @@ module.exports = AudioDetails;
  *
  * The controller for the Video Details state
  *
+ * @memberOf wp.media.controller
+ *
  * @class
  * @augments wp.media.controller.State
  * @augments Backbone.Model
@@ -325,7 +329,7 @@ var State = wp.media.controller.State,
 	l10n = wp.media.view.l10n,
 	VideoDetails;
 
-VideoDetails = State.extend({
+VideoDetails = State.extend(/** @lends wp.media.controller.VideoDetails.prototype */{
 	defaults: {
 		id: 'video-details',
 		toolbar: 'video-details',
@@ -351,10 +355,12 @@ module.exports = VideoDetails;
  * Shared model class for audio and video. Updates the model after
  *   "Add Audio|Video Source" and "Replace Audio|Video" states return
  *
+ * @memberOf wp.media.model
+ *
  * @class
  * @augments Backbone.Model
  */
-var PostMedia = Backbone.Model.extend({
+var PostMedia = Backbone.Model.extend(/** @lends wp.media.model.PostMedia.prototype */{
 	initialize: function() {
 		this.attachment = false;
 	},
@@ -387,9 +393,14 @@ var PostMedia = Backbone.Model.extend({
 module.exports = PostMedia;
 
 },{}],5:[function(require,module,exports){
+var MediaDetails = wp.media.view.MediaDetails,
+	AudioDetails;
+
 /**
  * wp.media.view.AudioDetails
  *
+ * @memberOf wp.media.view
+ *
  * @class
  * @augments wp.media.view.MediaDetails
  * @augments wp.media.view.Settings.AttachmentDisplay
@@ -398,10 +409,7 @@ module.exports = PostMedia;
  * @augments wp.Backbone.View
  * @augments Backbone.View
  */
-var MediaDetails = wp.media.view.MediaDetails,
+AudioDetails = MediaDetails.extend(/** @lends wp.media.view.AudioDetails.prototype */{
-	AudioDetails;
-
-AudioDetails = MediaDetails.extend({
 	className: 'audio-details',
 	template:  wp.template('audio-details'),
 
@@ -425,9 +433,17 @@ AudioDetails = MediaDetails.extend({
 module.exports = AudioDetails;
 
 },{}],6:[function(require,module,exports){
+var MediaDetails = wp.media.view.MediaFrame.MediaDetails,
+	MediaLibrary = wp.media.controller.MediaLibrary,
+
+	l10n = wp.media.view.l10n,
+	AudioDetails;
+
 /**
  * wp.media.view.MediaFrame.AudioDetails
  *
+ * @memberOf wp.media.view.MediaFrame
+ *
  * @class
  * @augments wp.media.view.MediaFrame.MediaDetails
  * @augments wp.media.view.MediaFrame.Select
@@ -438,13 +454,7 @@ module.exports = AudioDetails;
  * @augments Backbone.View
  * @mixes wp.media.controller.StateMachine
  */
-var MediaDetails = wp.media.view.MediaFrame.MediaDetails,
+AudioDetails = MediaDetails.extend(/** @lends wp.media.view.MediaFrame.AudioDetails.prototype */{
-	MediaLibrary = wp.media.controller.MediaLibrary,
-
-	l10n = wp.media.view.l10n,
-	AudioDetails;
-
-AudioDetails = MediaDetails.extend({
 	defaults: {
 		id:      'audio',
 		url:     '',
@@ -501,9 +511,15 @@ AudioDetails = MediaDetails.extend({
 module.exports = AudioDetails;
 
 },{}],7:[function(require,module,exports){
+var Select = wp.media.view.MediaFrame.Select,
+	l10n = wp.media.view.l10n,
+	MediaDetails;
+
 /**
  * wp.media.view.MediaFrame.MediaDetails
  *
+ * @memberOf wp.media.view.MediaFrame
+ *
  * @class
  * @augments wp.media.view.MediaFrame.Select
  * @augments wp.media.view.MediaFrame
@@ -513,11 +529,7 @@ module.exports = AudioDetails;
  * @augments Backbone.View
  * @mixes wp.media.controller.StateMachine
  */
-var Select = wp.media.view.MediaFrame.Select,
+MediaDetails = Select.extend(/** @lends wp.media.view.MediaFrame.MediaDetails.prototype */{
-	l10n = wp.media.view.l10n,
-	MediaDetails;
-
-MediaDetails = Select.extend({
 	defaults: {
 		id:      'media',
 		url:     '',
@@ -631,9 +643,16 @@ MediaDetails = Select.extend({
 module.exports = MediaDetails;
 
 },{}],8:[function(require,module,exports){
+var MediaDetails = wp.media.view.MediaFrame.MediaDetails,
+	MediaLibrary = wp.media.controller.MediaLibrary,
+	l10n = wp.media.view.l10n,
+	VideoDetails;
+
 /**
  * wp.media.view.MediaFrame.VideoDetails
  *
+ * @memberOf wp.media.view.MediaFrame
+ *
  * @class
  * @augments wp.media.view.MediaFrame.MediaDetails
  * @augments wp.media.view.MediaFrame.Select
@@ -644,12 +663,7 @@ module.exports = MediaDetails;
  * @augments Backbone.View
  * @mixes wp.media.controller.StateMachine
  */
-var MediaDetails = wp.media.view.MediaFrame.MediaDetails,
+VideoDetails = MediaDetails.extend(/** @lends wp.media.view.MediaFrame.VideoDetails.prototype */{
-	MediaLibrary = wp.media.controller.MediaLibrary,
-	l10n = wp.media.view.l10n,
-	VideoDetails;
-
-VideoDetails = MediaDetails.extend({
 	defaults: {
 		id:      'video',
 		url:     '',
@@ -767,10 +781,15 @@ module.exports = VideoDetails;
 
 },{}],9:[function(require,module,exports){
 /* global MediaElementPlayer */
+var AttachmentDisplay = wp.media.view.Settings.AttachmentDisplay,
+	$ = jQuery,
+	MediaDetails;
 
 /**
  * wp.media.view.MediaDetails
  *
+ * @memberOf wp.media.view
+ *
  * @class
  * @augments wp.media.view.Settings.AttachmentDisplay
  * @augments wp.media.view.Settings
@@ -778,11 +797,7 @@ module.exports = VideoDetails;
  * @augments wp.Backbone.View
  * @augments Backbone.View
  */
-var AttachmentDisplay = wp.media.view.Settings.AttachmentDisplay,
+MediaDetails = AttachmentDisplay.extend(/** @lends wp.media.view.MediaDetails.prototype */{
-	$ = jQuery,
-	MediaDetails;
-
-MediaDetails = AttachmentDisplay.extend({
 	initialize: function() {
 		_.bindAll(this, 'success');
 		this.players = [];
@@ -854,9 +869,6 @@ MediaDetails = AttachmentDisplay.extend({
 		this.scriptXhr = false;
 	},
 
-	/**
-	 * @global MediaElementPlayer
-	 */
 	setPlayer : function() {
 		var src;
 
@@ -912,7 +924,7 @@ MediaDetails = AttachmentDisplay.extend({
 	resetFocus: function() {
 		this.$( '.embed-media-settings' ).scrollTop( 0 );
 	}
-}, {
+},/** @lends wp.media.view.MediaDetails */{
 	instances : 0,
 	/**
 	 * When multiple players in the DOM contain the same src, things get weird.
@@ -938,9 +950,14 @@ MediaDetails = AttachmentDisplay.extend({
 module.exports = MediaDetails;
 
 },{}],10:[function(require,module,exports){
+var MediaDetails = wp.media.view.MediaDetails,
+	VideoDetails;
+
 /**
  * wp.media.view.VideoDetails
  *
+ * @memberOf wp.media.view
+ *
  * @class
  * @augments wp.media.view.MediaDetails
  * @augments wp.media.view.Settings.AttachmentDisplay
@@ -949,10 +966,7 @@ module.exports = MediaDetails;
  * @augments wp.Backbone.View
  * @augments Backbone.View
  */
-var MediaDetails = wp.media.view.MediaDetails,
+VideoDetails = MediaDetails.extend(/** @lends wp.media.view.VideoDetails.prototype */{
-	VideoDetails;
-
-VideoDetails = MediaDetails.extend({
 	className: 'video-details',
 	template:  wp.template('video-details'),
 

wp-includes/js/media-editor.js

@@ -30,19 +30,13 @@
 		return attrs[ key ];
 	};
 
-	/**
+	/** @namespace wp.media.string */
-	 * wp.media.string
-	 * @namespace
-	 */
 	wp.media.string = {
 		/**
 		 * Joins the `props` and `attachment` objects,
 		 * outputting the proper object format based on the
 		 * attachment's type.
 		 *
-		 * @global wp.media.view.settings
-		 * @global getUserSetting()
-		 *
 		 * @param {Object} [props={}] Attachment details (align, link, size, etc).
 		 * @param {Object} attachment The attachment object, media version of Post.
 		 * @returns {Object} Joined props
@@ -109,8 +103,6 @@
 		/**
 		 * Create link markup that is suitable for passing to the editor
 		 *
-		 * @global wp.html.string
-		 *
 		 * @param {Object} props Attachment details (align, link, size, etc).
 		 * @param {Object} attachment The attachment object, media version of Post.
 		 * @returns {string} The link markup
@@ -159,9 +151,6 @@
 		 *
 		 * @access private
 		 *
-		 * @global wp.shortcode
-		 * @global wp.media.view.settings
-		 *
 		 * @param {string} type The shortcode tag name: 'audio' or 'video'.
 		 * @param {Object} props Attachment details (align, link, size, etc).
 		 * @param {Object} attachment The attachment object, media version of Post.
@@ -210,9 +199,6 @@
 		 * Create image markup, optionally with a link and/or wrapped in a caption shortcode,
 		 *  that is suitable for passing to the editor
 		 *
-		 * @global wp.html
-		 * @global wp.shortcode
-		 *
 		 * @param {Object} props Attachment details (align, link, size, etc).
 		 * @param {Object} attachment The attachment object, media version of Post.
 		 * @returns {string}
@@ -341,16 +327,19 @@
 		}
 	};
 
+	/**
+	 * @class wp.media.collection
+	 *
+	 * @param {Object} attributes
+	 */
 	wp.media.collection = function(attributes) {
 		var collections = {};
 
-		return _.extend( {
+		return _.extend(/** @lends wp.media.collection.prototype */{
 			coerce : wp.media.coerce,
 			/**
 			 * Retrieve attachments based on the properties of the passed shortcode
 			 *
-			 * @global wp.media.query
-			 *
 			 * @param {wp.shortcode} shortcode An instance of wp.shortcode().
 			 * @returns {wp.media.model.Attachments} A Backbone.Collection containing
 			 *      the media items belonging to a collection.
@@ -417,9 +406,6 @@
 			/**
 			 * Triggered when clicking 'Insert {label}' or 'Update {label}'
 			 *
-			 * @global wp.shortcode
-			 * @global wp.media.model.Attachments
-			 *
 			 * @param {wp.media.model.Attachments} attachments A Backbone.Collection containing
 			 *      the media items belonging to a collection.
 			 *      The query[ this.tag ] property is a Backbone.Model
@@ -488,10 +474,6 @@
 			 * Triggered when double-clicking a collection shortcode placeholder
 			 *   in the editor
 			 *
-			 * @global wp.shortcode
-			 * @global wp.media.model.Selection
-			 * @global wp.media.view.l10n
-			 *
 			 * @param {string} content Content that is searched for possible
 			 *    shortcode markup matching the passed tag name,
 			 *
@@ -610,15 +592,13 @@
 	});
 
 	/**
-	 * wp.media.featuredImage
+	 * @namespace wp.media.featuredImage
-	 * @namespace
+	 * @memberOf wp.media
 	 */
 	wp.media.featuredImage = {
 		/**
 		 * Get the featured image post ID
 		 *
-		 * @global wp.media.view.settings
-		 *
 		 * @returns {wp.media.view.settings.post.featuredImageId|number}
 		 */
 		get: function() {
@@ -628,9 +608,6 @@
 		 * Set the featured image id, save the post thumbnail data and
 		 * set the HTML in the post meta box to the new featured image.
 		 *
-		 * @global wp.media.view.settings
-		 * @global wp.media.post
-		 *
 		 * @param {number} id The post ID of the featured image, or -1 to unset it.
 		 */
 		set: function( id ) {
@@ -660,9 +637,6 @@
 		/**
 		 * The Featured Image workflow
 		 *
-		 * @global wp.media.controller.FeaturedImage
-		 * @global wp.media.view.l10n
-		 *
 		 * @this wp.media.featuredImage
 		 *
 		 * @returns {wp.media.view.MediaFrame.Select} A media workflow.
@@ -705,8 +679,6 @@
 		 * 'select' callback for Featured Image workflow, triggered when
 		 *  the 'Set Featured Image' button is clicked in the media modal.
 		 *
-		 * @global wp.media.view.settings
-		 *
 		 * @this wp.media.controller.FeaturedImage
 		 */
 		select: function() {
@@ -723,8 +695,6 @@
 		 * the post thumbnail is clicked.
 		 *
 		 * Update the featured image id when the 'remove' link is clicked.
-		 *
-		 * @global wp.media.view.settings
 		 */
 		init: function() {
 			$('#postimagediv').on( 'click', '#set-post-thumbnail', function( event ) {
@@ -742,19 +712,11 @@
 
 	$( wp.media.featuredImage.init );
 
-	/**
+	/** @namespace wp.media.editor */
-	 * wp.media.editor
-	 * @namespace
-	 */
 	wp.media.editor = {
 		/**
 		 * Send content to the editor
 		 *
-		 * @global tinymce
-		 * @global QTags
-		 * @global wpActiveEditor
-		 * @global tb_remove() - Possibly overloaded by legacy plugins
-		 *
 		 * @param {string} html Content to send to the editor
 		 */
 		insert: function( html ) {
@@ -805,8 +767,6 @@
 		 * Setup 'workflow' and add to the 'workflows' cache. 'open' can
 		 *  subsequently be called upon it.
 		 *
-		 * @global wp.media.view.l10n
-		 *
 		 * @param {string} id A slug used to identify the workflow.
 		 * @param {Object} [options={}]
 		 *
@@ -914,9 +874,6 @@
 		/**
 		 * Determines the proper current workflow id
 		 *
-		 * @global wpActiveEditor
-		 * @global tinymce
-		 *
 		 * @param {string} [id=''] A slug used to identify the workflow.
 		 *
 		 * @returns {wpActiveEditor|string|tinymce.activeEditor.id}
@@ -962,17 +919,12 @@
 			id = this.id( id );
 			delete workflows[ id ];
 		},
-		/**
+		/** @namespace wp.media.editor.send */
-		 * @namespace
-		 */
 		send: {
 			/**
 			 * Called when sending an attachment to the editor
 			 *   from the medial modal.
 			 *
-			 * @global wp.media.view.settings
-			 * @global wp.media.post
-			 *
 			 * @param {Object} props Attachment details (align, link, size, etc).
 			 * @param {Object} attachment The attachment object, media version of Post.
 			 * @returns {Promise}
@@ -1028,8 +980,6 @@
 			/**
 			 * Called when 'Insert From URL' source is not an image. Example: YouTube url.
 			 *
-			 * @global wp.media.view.settings
-			 *
 			 * @param {Object} embed
 			 * @returns {Promise}
 			 */
@@ -1075,8 +1025,6 @@
 
 		/**
 		 * Bind click event for .insert-media using event delegation
-		 *
-		 * @global wp.media.view.l10n
 		 */
 		init: function() {
 			$(document.body)

wp-includes/js/media-grid.js

@@ -1,17 +1,19 @@
 (function e(t,n,r){function s(o,u){if(!n[o]){if(!t[o]){var a=typeof require=="function"&&require;if(!u&&a)return a(o,!0);if(i)return i(o,!0);var f=new Error("Cannot find module '"+o+"'");throw f.code="MODULE_NOT_FOUND",f}var l=n[o]={exports:{}};t[o][0].call(l.exports,function(e){var n=t[o][1][e];return s(n?n:e)},l,l.exports,e,t,n,r)}return n[o].exports}var i=typeof require=="function"&&require;for(var o=0;o<r.length;o++)s(r[o]);return s})({1:[function(require,module,exports){
+var l10n = wp.media.view.l10n,
+	EditAttachmentMetadata;
+
 /**
  * wp.media.controller.EditAttachmentMetadata
  *
  * A state for editing an attachment's metadata.
  *
+ * @memberOf wp.media.controller
+ *
  * @class
  * @augments wp.media.controller.State
  * @augments Backbone.Model
  */
-var l10n = wp.media.view.l10n,
+EditAttachmentMetadata = wp.media.controller.State.extend(/** @lends wp.media.controller.EditAttachmentMetadata.prototype */{
-	EditAttachmentMetadata;
-
-EditAttachmentMetadata = wp.media.controller.State.extend({
 	defaults: {
 		id:      'edit-attachment',
 		// Title string passed to the frame's title region view.
@@ -45,10 +47,12 @@ media.view.DeleteSelectedPermanentlyButton = require( './views/button/delete-sel
  *
  * A router for handling the browser history and application state.
  *
+ * @memberOf wp.media.view.MediaFrame.Manage
+ *
  * @class
  * @augments Backbone.Router
  */
-var Router = Backbone.Router.extend({
+var Router = Backbone.Router.extend(/** @lends wp.media.view.MediaFrame.Manage.Router.prototype */{
 	routes: {
 		'upload.php?item=:slug&mode=edit': 'editItem',
 		'upload.php?item=:slug':           'showItem',
@@ -107,12 +111,17 @@ var Router = Backbone.Router.extend({
 module.exports = Router;
 
 },{}],4:[function(require,module,exports){
+var Details = wp.media.view.Attachment.Details,
+	TwoColumn;
+
 /**
  * wp.media.view.Attachment.Details.TwoColumn
  *
  * A similar view to media.view.Attachment.Details
  * for use in the Edit Attachment modal.
  *
+ * @memberOf wp.media.view.Attachment.Details
+ *
  * @class
  * @augments wp.media.view.Attachment.Details
  * @augments wp.media.view.Attachment
@@ -120,10 +129,7 @@ module.exports = Router;
  * @augments wp.Backbone.View
  * @augments Backbone.View
  */
-var Details = wp.media.view.Attachment.Details,
+TwoColumn = Details.extend(/** @lends wp.media.view.Attachment.Details.TowColumn.prototype */{
-	TwoColumn;
-
-TwoColumn = Details.extend({
 	template: wp.template( 'attachment-details-two-column' ),
 
 	initialize: function() {
@@ -158,11 +164,17 @@ TwoColumn = Details.extend({
 module.exports = TwoColumn;
 
 },{}],5:[function(require,module,exports){
+var Button = wp.media.view.Button,
+	DeleteSelected = wp.media.view.DeleteSelectedButton,
+	DeleteSelectedPermanently;
+
 /**
  * wp.media.view.DeleteSelectedPermanentlyButton
  *
  * When MEDIA_TRASH is true, a button that handles bulk Delete Permanently logic
  *
+ * @memberOf wp.media.view
+ *
  * @class
  * @augments wp.media.view.DeleteSelectedButton
  * @augments wp.media.view.Button
@@ -170,11 +182,7 @@ module.exports = TwoColumn;
  * @augments wp.Backbone.View
  * @augments Backbone.View
  */
-var Button = wp.media.view.Button,
+DeleteSelectedPermanently = DeleteSelected.extend(/** @lends wp.media.view.DeleteSelectedPermanentlyButton.prototype */{
-	DeleteSelected = wp.media.view.DeleteSelectedButton,
-	DeleteSelectedPermanently;
-
-DeleteSelectedPermanently = DeleteSelected.extend({
 	initialize: function() {
 		DeleteSelected.prototype.initialize.apply( this, arguments );
 		this.controller.on( 'select:activate', this.selectActivate, this );
@@ -205,22 +213,24 @@ DeleteSelectedPermanently = DeleteSelected.extend({
 module.exports = DeleteSelectedPermanently;
 
 },{}],6:[function(require,module,exports){
+var Button = wp.media.view.Button,
+	l10n = wp.media.view.l10n,
+	DeleteSelected;
+
 /**
  * wp.media.view.DeleteSelectedButton
  *
  * A button that handles bulk Delete/Trash logic
  *
+ * @memberOf wp.media.view
+ *
  * @class
  * @augments wp.media.view.Button
  * @augments wp.media.View
  * @augments wp.Backbone.View
  * @augments Backbone.View
  */
-var Button = wp.media.view.Button,
+DeleteSelected = Button.extend(/** @lends wp.media.view.DeleteSelectedButton.prototype */{
-	l10n = wp.media.view.l10n,
-	DeleteSelected;
-
-DeleteSelected = Button.extend({
 	initialize: function() {
 		Button.prototype.initialize.apply( this, arguments );
 		if ( this.options.filters ) {
@@ -258,20 +268,23 @@ DeleteSelected = Button.extend({
 module.exports = DeleteSelected;
 
 },{}],7:[function(require,module,exports){
+
+var Button = wp.media.view.Button,
+	l10n = wp.media.view.l10n,
+	SelectModeToggle;
+
 /**
  * wp.media.view.SelectModeToggleButton
  *
+ * @memberOf wp.media.view
+ *
  * @class
  * @augments wp.media.view.Button
  * @augments wp.media.View
  * @augments wp.Backbone.View
  * @augments Backbone.View
  */
-var Button = wp.media.view.Button,
+SelectModeToggle = Button.extend(/** @lends wp.media.view.SelectModeToggle.prototype */{
-	l10n = wp.media.view.l10n,
-	SelectModeToggle;
-
-SelectModeToggle = Button.extend({
 	initialize: function() {
 		_.defaults( this.options, {
 			size : ''
@@ -332,20 +345,22 @@ SelectModeToggle = Button.extend({
 module.exports = SelectModeToggle;
 
 },{}],8:[function(require,module,exports){
+var View = wp.media.View,
+	EditImage = wp.media.view.EditImage,
+	Details;
+
 /**
  * wp.media.view.EditImage.Details
  *
+ * @memberOf wp.media.view.EditImage
+ *
  * @class
  * @augments wp.media.view.EditImage
  * @augments wp.media.View
  * @augments wp.Backbone.View
  * @augments Backbone.View
  */
-var View = wp.media.View,
+Details = EditImage.extend(/** @lends wp.media.view.EditImage.Details.prototype */{
-	EditImage = wp.media.view.EditImage,
-	Details;
-
-Details = EditImage.extend({
 	initialize: function( options ) {
 		this.editor = window.imageEdit;
 		this.frame = options.frame;
@@ -367,6 +382,12 @@ Details = EditImage.extend({
 module.exports = Details;
 
 },{}],9:[function(require,module,exports){
+var Frame = wp.media.view.Frame,
+	MediaFrame = wp.media.view.MediaFrame,
+
+	$ = jQuery,
+	EditAttachments;
+
 /**
  * wp.media.view.MediaFrame.EditAttachments
  *
@@ -376,6 +397,8 @@ module.exports = Details;
  *
  * Requires an attachment model to be passed in the options hash under `model`.
  *
+ * @memberOf wp.media.view.MediaFrame
+ *
  * @class
  * @augments wp.media.view.Frame
  * @augments wp.media.View
@@ -383,13 +406,7 @@ module.exports = Details;
  * @augments Backbone.View
  * @mixes wp.media.controller.StateMachine
  */
-var Frame = wp.media.view.Frame,
+EditAttachments = MediaFrame.extend(/** @lends wp.media.view.MediaFrame.EditAttachments.prototype */{
-	MediaFrame = wp.media.view.MediaFrame,
-
-	$ = jQuery,
-	EditAttachments;
-
-EditAttachments = MediaFrame.extend({
 
 	className: 'edit-attachment-frame',
 	template:  wp.template( 'edit-attachment-frame' ),
@@ -627,6 +644,12 @@ EditAttachments = MediaFrame.extend({
 module.exports = EditAttachments;
 
 },{}],10:[function(require,module,exports){
+var MediaFrame = wp.media.view.MediaFrame,
+	Library = wp.media.controller.Library,
+
+	$ = Backbone.$,
+	Manage;
+
 /**
  * wp.media.view.MediaFrame.Manage
  *
@@ -634,6 +657,8 @@ module.exports = EditAttachments;
  *
  * Used in the media grid view.
  *
+ * @memberOf wp.media.view.MediaFrame
+ *
  * @class
  * @augments wp.media.view.MediaFrame
  * @augments wp.media.view.Frame
@@ -642,15 +667,9 @@ module.exports = EditAttachments;
  * @augments Backbone.View
  * @mixes wp.media.controller.StateMachine
  */
-var MediaFrame = wp.media.view.MediaFrame,
+Manage = MediaFrame.extend(/** @lends wp.media.view.MediaFrame.Manage.prototype */{
-	Library = wp.media.controller.Library,
-
-	$ = Backbone.$,
-	Manage;
-
-Manage = MediaFrame.extend({
 	/**
-	 * @global wp.Uploader
+	 * @constructs
 	 */
 	initialize: function() {
 		_.defaults( this.options, {

wp-includes/js/media-models.js

@@ -2,6 +2,7 @@
 var $ = jQuery,
 	Attachment, Attachments, l10n, media;
 
+/** @namespace wp */
 window.wp = window.wp || {};
 
 /**
@@ -9,6 +10,9 @@ window.wp = window.wp || {};
  *
  * Handles the default media experience.
  *
+ * @alias wp.media
+ * @memberOf wp
+ *
  * @param  {object} attributes The properties passed to the main media controller.
  * @return {wp.media.view.MediaFrame} A media workflow.
  */
@@ -47,6 +51,11 @@ media = wp.media = function( attributes ) {
 	return frame;
 };
 
+/** @namespace wp.media */
+/** @namespace wp.media.model */
+/** @namespace wp.media.view */
+/** @namespace wp.media.controller */
+/** @namespace wp.media.frames */
 _.extend( media, { model: {}, view: {}, controller: {}, frames: {} });
 
 // Link any localized strings.
@@ -90,7 +99,7 @@ media.compare = function( a, b, ac, bc ) {
 	}
 };
 
-_.extend( media, {
+_.extend( media, /** @lends wp.media */{
 	/**
 	 * media.template( id )
 	 *
@@ -230,16 +239,18 @@ $(window).on('unload', function(){
 });
 
 },{"./models/attachment.js":2,"./models/attachments.js":3,"./models/post-image.js":4,"./models/query.js":5,"./models/selection.js":6}],2:[function(require,module,exports){
+var $ = Backbone.$,
+	Attachment;
+
 /**
  * wp.media.model.Attachment
  *
+ * @memberOf wp.media.model
+ *
  * @class
  * @augments Backbone.Model
  */
-var $ = Backbone.$,
+Attachment = Backbone.Model.extend(/** @lends wp.media.model.Attachment.prototype */{
-	Attachment;
-
-Attachment = Backbone.Model.extend({
 	/**
 	 * Triggered when attachment details change
 	 * Overrides Backbone.Model.sync
@@ -366,11 +377,12 @@ Attachment = Backbone.Model.extend({
 			model.set( model.parse( resp, xhr ), options );
 		});
 	}
-}, {
+},/** @lends wp.media.model.Attachment */{
 	/**
 	 * Create a new model on the static 'all' attachments collection and return it.
 	 *
 	 * @static
+	 *
 	 * @param {Object} attrs
 	 * @returns {wp.media.model.Attachment}
 	 */
@@ -407,6 +419,8 @@ module.exports = Attachment;
  * 'options.props.query = true', which will mirror the collection
  * to an Attachments Query collection - @see wp.media.model.Attachments.mirror().
  *
+ * @memberOf wp.media.model
+ *
  * @class
  * @augments Backbone.Collection
  *
@@ -420,7 +434,7 @@ module.exports = Attachment;
  * @param {string} [options.filters]
  *
  */
-var Attachments = Backbone.Collection.extend({
+var Attachments = Backbone.Collection.extend(/** @lends wp.media.model.Attachments.prototype */{
 	/**
 	 * @type {wp.media.model.Attachment}
 	 */
@@ -818,15 +832,13 @@ var Attachments = Backbone.Collection.extend({
 			attachments: attachments
 		});
 	}
-}, {
+},/** @lends wp.media.model.Attachments */{
 	/**
 	 * A function to compare two attachment models in an attachments collection.
 	 *
 	 * Used as the default comparator for instances of wp.media.model.Attachments
 	 * and its subclasses. @see wp.media.model.Attachments._changeOrderby().
 	 *
-	 * @static
-	 *
 	 * @param {Backbone.Model} a
 	 * @param {Backbone.Model} b
 	 * @param {Object} options
@@ -855,9 +867,7 @@ var Attachments = Backbone.Collection.extend({
 
 		return ( 'DESC' === order ) ? wp.media.compare( a, b, ac, bc ) : wp.media.compare( b, a, bc, ac );
 	},
-	/**
+	/** @namespace wp.media.model.Attachments.filters */
-	 * @namespace
-	 */
 	filters: {
 		/**
 		 * @static
@@ -952,13 +962,15 @@ module.exports = Attachments;
  *
  * Used in the embedded image attachment display settings modal - @see wp.media.view.MediaFrame.ImageDetails.
  *
+ * @memberOf wp.media.model
+ *
  * @class
  * @augments Backbone.Model
  *
  * @param {int} [attributes]               Initial model attributes.
  * @param {int} [attributes.attachment_id] ID of the attachment.
  **/
-var PostImage = Backbone.Model.extend({
+var PostImage = Backbone.Model.extend(/** @lends wp.media.model.PostImage.prototype */{
 
 	initialize: function( attributes ) {
 		var Attachment = wp.media.model.Attachment;
@@ -1099,6 +1111,9 @@ var PostImage = Backbone.Model.extend({
 module.exports = PostImage;
 
 },{}],5:[function(require,module,exports){
+var Attachments = wp.media.model.Attachments,
+	Query;
+
 /**
  * wp.media.model.Query
  *
@@ -1107,6 +1122,8 @@ module.exports = PostImage;
  * Note: Do NOT change this.args after the query has been initialized.
  *       Things will break.
  *
+ * @memberOf wp.media.model
+ *
  * @class
  * @augments wp.media.model.Attachments
  * @augments Backbone.Collection
@@ -1116,13 +1133,8 @@ module.exports = PostImage;
  * @param {object} [options.args]                Attachments query arguments.
  * @param {object} [options.args.posts_per_page]
  */
-var Attachments = wp.media.model.Attachments,
+Query = Attachments.extend(/** @lends wp.media.model.Query.prototype */{
-	Query;
-
-Query = Attachments.extend({
 	/**
-	 * @global wp.Uploader
-	 *
 	 * @param {array}  [models=[]]  Array of initial models to populate the collection.
 	 * @param {object} [options={}]
 	 */
@@ -1254,7 +1266,7 @@ Query = Attachments.extend({
 			return fallback.sync.apply( this, arguments );
 		}
 	}
-}, {
+}, /** @lends wp.media.model.Query */{
 	/**
 	 * @readonly
 	 */
@@ -1407,19 +1419,21 @@ Query = Attachments.extend({
 module.exports = Query;
 
 },{}],6:[function(require,module,exports){
+var Attachments = wp.media.model.Attachments,
+	Selection;
+
 /**
  * wp.media.model.Selection
  *
  * A selection of attachments.
  *
+ * @memberOf wp.media.model
+ *
  * @class
  * @augments wp.media.model.Attachments
  * @augments Backbone.Collection
  */
-var Attachments = wp.media.model.Attachments,
+Selection = Attachments.extend(/** @lends wp.media.model.Selection.prototype */{
-	Selection;
-
-Selection = Attachments.extend({
 	/**
 	 * Refresh the `single` model whenever the selection changes.
 	 * Binds `single` instead of using the context argument to ensure

wp-includes/js/plupload/wp-plupload.js

@@ -198,7 +198,6 @@ window.wp = window.wp || {};
 		/**
 		 * After files were filtered and added to the queue, create a model for each.
 		 *
-		 * @event FilesAdded
 		 * @param {plupload.Uploader} uploader Uploader instance.
 		 * @param {Array}             files    Array of file objects that were added to queue by the user.
 		 */
@@ -340,7 +339,7 @@ window.wp = window.wp || {};
 		}
 	};
 
-	$.extend( Uploader.prototype, {
+	$.extend( Uploader.prototype, /** @lends wp.Uploader.prototype */{
 		/**
 		 * Acts as a shortcut to extending the uploader's multipart_params object.
 		 *

wp-includes/js/shortcode.js

@@ -1,6 +1,10 @@
 // Utility functions for parsing and handling shortcodes in JavaScript.
 
-// Ensure the global `wp` object exists.
+/**
+ * Ensure the global `wp` object exists.
+ *
+ * @namespace wp
+ */
 window.wp = window.wp || {};
 
 (function(){

wp-includes/js/wp-a11y.js

@@ -1,3 +1,4 @@
+/** @namespace wp */
 window.wp = window.wp || {};
 
 ( function ( wp, $ ) {
@@ -94,6 +95,7 @@ window.wp = window.wp || {};
 		}
 	});
 
+	/** @namespace wp.a11y */
 	wp.a11y = wp.a11y || {};
 	wp.a11y.speak = speak;
 

wp-includes/js/wp-api.js

@@ -6,12 +6,17 @@
 	 * Initialise the WP_API.
 	 */
 	function WP_API() {
+		/** @namespace wp.api.models */
 		this.models = {};
+		/** @namespace wp.api.collections */
 		this.collections = {};
+		/** @namespace wp.api.views */
 		this.views = {};
 	}
 
+	/** @namespace wp */
 	window.wp            = window.wp || {};
+	/** @namespace wp.api */
 	wp.api               = wp.api || new WP_API();
 	wp.api.versionString = wp.api.versionString || 'wp/v2/';
 
@@ -28,8 +33,11 @@
 
 	var pad, r;
 
+	/** @namespace wp */
 	window.wp = window.wp || {};
+	/** @namespace wp.api */
 	wp.api = wp.api || {};
+	/** @namespace wp.api.utils */
 	wp.api.utils = wp.api.utils || {};
 
 	/**
@@ -1024,7 +1032,11 @@
 
 	var Endpoint, initializedDeferreds = {},
 		wpApiSettings = window.wpApiSettings || {};
+
+	/** @namespace wp */
 	window.wp = window.wp || {};
+
+	/** @namespace wp.api */
 	wp.api    = wp.api || {};
 
 	// If wpApiSettings is unavailable, try the default.
@@ -1032,7 +1044,7 @@
 		wpApiSettings.root = window.location.origin + '/wp-json/';
 	}
 
-	Endpoint = Backbone.Model.extend( {
+	Endpoint = Backbone.Model.extend(/** @lends Endpoint.prototype */{
 		defaults: {
 			apiRoot: wpApiSettings.root,
 			versionString: wp.api.versionString,
@@ -1081,6 +1093,8 @@
 					 * When the server returns the schema model data, store the data in a sessionCache so we don't
 					 * have to retrieve it again for this session. Then, construct the models and collections based
 					 * on the schema model data.
+					 *
+					 * @callback
 					 */
 					success: function( newSchemaModel ) {
 

wp-includes/js/wp-backbone.js

@@ -1,7 +1,12 @@
+/** @namespace wp */
 window.wp = window.wp || {};
 
 (function ($) {
-	// Create the WordPress Backbone namespace.
+	/**
+	 * Create the WordPress Backbone namespace.
+	 *
+	 * @namespace wp.Backbone
+	 */
 	wp.Backbone = {};
 
 

wp-includes/js/wp-custom-header.js

@@ -3,6 +3,7 @@
 
 	var NativeHandler, YouTubeHandler;
 
+	/** @namespace wp */
 	window.wp = window.wp || {};
 
 	// Fail gracefully in unsupported browsers.
@@ -32,7 +33,9 @@
 	/**
 	 * Create a custom header instance.
 	 *
-	 * @class CustomHeader
+	 * @memberOf wp
+	 *
+	 * @class
 	 */
 	function CustomHeader() {
 		this.handlers = {
@@ -91,7 +94,9 @@
 	/**
 	 * Create a video handler instance.
 	 *
-	 * @class BaseHandler
+	 * @memberOf wp
+	 *
+	 * @class
 	 */
 	function BaseHandler() {}
 
@@ -228,6 +233,8 @@
 	/**
 	 * Create a custom handler.
 	 *
+	 * @memberOf wp
+	 *
 	 * @param {object} protoProps Properties to apply to the prototype.
 	 * @return CustomHandler The subclass.
 	 */
@@ -252,9 +259,11 @@
 	/**
 	 * Native video handler.
 	 *
-	 * @class NativeHandler
+	 * @memberOf wp
+	 *
+	 * @class
 	 */
-	NativeHandler = BaseHandler.extend({
+	NativeHandler = BaseHandler.extend(/** @lends wp.NativeHandler.prototype */{
 		/**
 		 * Whether the native handler supports a video.
 		 *
@@ -324,9 +333,11 @@
 	/**
 	 * YouTube video handler.
 	 *
-	 * @class YouTubeHandler
+	 * @memberOf wp
+	 *
+	 * @class wp.YouTubeHandler
 	 */
-	YouTubeHandler = BaseHandler.extend({
+	YouTubeHandler = BaseHandler.extend(/** @lends wp.YouTubeHandler.prototype */{
 		/**
 		 * Whether the handler supports a video.
 		 *

wp-includes/js/wp-embed.js

@@ -19,6 +19,7 @@
 			}
 		}
 
+	/** @namespace wp */
 	window.wp = window.wp || {};
 
 	if ( !! window.wp.receiveEmbedMessage ) {

wp-includes/js/wp-pointer.js

@@ -6,7 +6,10 @@
 	var identifier = 0,
 		zindex = 9999;
 
-	$.widget('wp.pointer', {
+	/**
+	 * @class $.widget.wp.pointer
+	 */
+	$.widget('wp.pointer',/** @lends $.widget.wp.pointer.prototype */{
 		options: {
 			pointerClass: 'wp-pointer',
 			pointerWidth: 320,

wp-includes/js/wp-util.js

@@ -1,4 +1,6 @@
 /* global _wpUtilSettings */
+
+/** @namespace wp */
 window.wp = window.wp || {};
 
 (function ($) {

wp-includes/version.php

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