mirror_php/wordpress
1
0
Fork 0
mirror of git://develop.git.wordpress.org/ synced 2025-01-17 04:48:25 +01:00
Code Issues Actions 98 Packages Projects Releases Wiki Activity

Docs: Improve wp-admin JSDoc structural data globally.

Browse Source 
JSDoc takes it structural data from `@namespace`, `@lends` and `@memberOf`. This change fixes these tags for all JavaScript files in the wp-admin folder.

* Add jsdoc configuration to parse wp-admin/js files. Use `jsdoc -c jsdoc.conf.json` to generate JSDoc.
* Define all used namespaces using `@namespace`.
* Define each usage of the extend function as a prototype assignment using `@lends`.
* Add `@alias` if JSDoc cannot detect the correct name automatically.

This has previously been corrected for all `wp-includes` JavaScript files: [41351].

Props herregroen.
Fixes #42485.


git-svn-id: https://develop.svn.wordpress.org/trunk@42403 602fd350-edb4-49c9-b593-d223f7449a82
This commit is contained in:
Anton Timmermans 2017-12-15 13:41:56 +00:00
parent 617372e21e
commit 53f1c74e1c
30 changed files with 597 additions and 462 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
jsdoc.conf.json
View File

@ -2,14 +2,23 @@
"plugins": [], "plugins": [],
"recurseDepth": 10, "recurseDepth": 10,
"source": { "source": {
"include": ["src/wp-includes/js"], "include": [
"src/wp-includes/js",
"src/wp-admin/js"
],
"exclude": [ "exclude": [
"src/wp-includes/js/codemirror",
"src/wp-includes/js/tinymce", "src/wp-includes/js/tinymce",
"src/wp-includes/js/crop", "src/wp-includes/js/crop",
"src/wp-includes/js/imgareaselect", "src/wp-includes/js/imgareaselect",
"src/wp-includes/js/jcrop", "src/wp-includes/js/jcrop",
"src/wp-includes/js/jquery", "src/wp-includes/js/jquery",
"src/wp-includes/js/mediaelement", "src/wp-includes/js/mediaelement/mediaelement.js",
"src/wp-includes/js/mediaelement/mediaelement-and-player.js",
"src/wp-includes/js/plupload/handlers.js",
"src/wp-includes/js/plupload/moxie.js",
"src/wp-includes/js/plupload/plupload.full.min.js",
"src/wp-includes/js/plupload/plupload.js",
"src/wp-includes/js/swfupload", "src/wp-includes/js/swfupload",
"src/wp-includes/js/thickbox", "src/wp-includes/js/thickbox",
"src/wp-includes/js/media-audiovideo.js", "src/wp-includes/js/media-audiovideo.js",
@ -35,6 +44,7 @@
}, },
"opts": { "opts": {
"template": "./node_modules/ink-docstrap/template", "template": "./node_modules/ink-docstrap/template",
"recurse": true "recurse": true,
"private": true
} }
} }

11
src/wp-admin/js/code-editor.js
View File

@ -1,7 +1,13 @@
if ( 'undefined' === typeof window.wp ) { if ( 'undefined' === typeof window.wp ) {
/**
* @namespace wp
*/
window.wp = {}; window.wp = {};
} }
if ( 'undefined' === typeof window.wp.codeEditor ) { if ( 'undefined' === typeof window.wp.codeEditor ) {
/**
* @namespace wp.codeEditor
*/
window.wp.codeEditor = {}; window.wp.codeEditor = {};
} }
@ -33,6 +39,7 @@ if ( 'undefined' === typeof window.wp.codeEditor ) {
* @param {object} settings.codeMirror - Settings for CodeMirror. * @param {object} settings.codeMirror - Settings for CodeMirror.
* @param {Function} settings.onChangeLintingErrors - Callback for when there are changes to linting errors. * @param {Function} settings.onChangeLintingErrors - Callback for when there are changes to linting errors.
* @param {Function} settings.onUpdateErrorNotice - Callback to update error notice. * @param {Function} settings.onUpdateErrorNotice - Callback to update error notice.
*
* @returns {void} * @returns {void}
*/ */
function configureLinting( editor, settings ) { // eslint-disable-line complexity function configureLinting( editor, settings ) { // eslint-disable-line complexity
@ -202,6 +209,7 @@ if ( 'undefined' === typeof window.wp.codeEditor ) {
* @param {object} settings.codeMirror - Settings for CodeMirror. * @param {object} settings.codeMirror - Settings for CodeMirror.
* @param {Function} settings.onTabNext - Callback to handle tabbing to the next tabbable element. * @param {Function} settings.onTabNext - Callback to handle tabbing to the next tabbable element.
* @param {Function} settings.onTabPrevious - Callback to handle tabbing to the previous tabbable element. * @param {Function} settings.onTabPrevious - Callback to handle tabbing to the previous tabbable element.
*
* @returns {void} * @returns {void}
*/ */
function configureTabbing( codemirror, settings ) { function configureTabbing( codemirror, settings ) {
@ -240,7 +248,7 @@ if ( 'undefined' === typeof window.wp.codeEditor ) {
} }
/** /**
* @typedef {object} CodeEditorInstance * @typedef {object} wp.codeEditor~CodeEditorInstance
* @property {object} settings - The code editor settings. * @property {object} settings - The code editor settings.
* @property {CodeMirror} codemirror - The CodeMirror instance. * @property {CodeMirror} codemirror - The CodeMirror instance.
*/ */
@ -260,6 +268,7 @@ if ( 'undefined' === typeof window.wp.codeEditor ) {
* @param {object} [settings.csslint] - Rules for CSSLint. * @param {object} [settings.csslint] - Rules for CSSLint.
* @param {object} [settings.htmlhint] - Rules for HTMLHint. * @param {object} [settings.htmlhint] - Rules for HTMLHint.
* @param {object} [settings.jshint] - Rules for JSHint. * @param {object} [settings.jshint] - Rules for JSHint.
*
* @returns {CodeEditorInstance} Instance. * @returns {CodeEditorInstance} Instance.
*/ */
wp.codeEditor.initialize = function initialize( textarea, settings ) { wp.codeEditor.initialize = function initialize( textarea, settings ) {

8
src/wp-admin/js/color-picker.js
View File

@ -14,9 +14,11 @@
* *
* Creates a jQuery UI color picker that is used in the theme customizer. * Creates a jQuery UI color picker that is used in the theme customizer.
* *
* @class $.widget.wp.wpColorPicker
*
* @since 3.5.0 * @since 3.5.0
*/ */
ColorPicker = { ColorPicker = /** @lends $.widget.wp.wpColorPicker.prototype */{
options: { options: {
defaultColor: false, defaultColor: false,
change: false, change: false,
@ -56,6 +58,8 @@
/** /**
* @summary Handles the onChange event if one has been defined in the options. * @summary Handles the onChange event if one has been defined in the options.
* *
* @ignore
*
* @param {Event} event The event that's being called. * @param {Event} event The event that's being called.
* @param {HTMLElement} ui The HTMLElement containing the color picker. * @param {HTMLElement} ui The HTMLElement containing the color picker.
* *
@ -179,6 +183,8 @@
* *
* @since 3.5.0 * @since 3.5.0
* *
* @ignore
*
* @param {Event} event The event that's being called. * @param {Event} event The event that's being called.
* @param {HTMLElement} ui The HTMLElement containing the color picker. * @param {HTMLElement} ui The HTMLElement containing the color picker.
* *

388
src/wp-admin/js/customize-controls.js
View File

@ -2,14 +2,7 @@
(function( exports, $ ){ (function( exports, $ ){
var Container, focus, normalizedTransitionendEventName, api = wp.customize; var Container, focus, normalizedTransitionendEventName, api = wp.customize;
/** api.OverlayNotification = api.Notification.extend(/** @lends wp.customize.OverlayNotification.prototype */{
* A notification that is displayed in a full-screen overlay.
*
* @since 4.9.0
* @class
* @augments wp.customize.Notification
*/
api.OverlayNotification = api.Notification.extend({
/** /**
* Whether the notification should show a loading spinner. * Whether the notification should show a loading spinner.
@ -20,7 +13,10 @@
loading: false, loading: false,
/** /**
* Initialize. * A notification that is displayed in a full-screen overlay.
*
* @constructs wp.customize.OverlayNotification
* @augments wp.customize.Notification
* *
* @since 4.9.0 * @since 4.9.0
* *
@ -68,14 +64,7 @@
} }
}); });
/** api.Notifications = api.Values.extend(/** @lends wp.customize.Notifications.prototype */{
* A collection of observable notifications.
*
* @since 4.9.0
* @class
* @augments wp.customize.Values
*/
api.Notifications = api.Values.extend({
/** /**
* Whether the alternative style should be used. * Whether the alternative style should be used.
@ -94,15 +83,18 @@
defaultConstructor: api.Notification, defaultConstructor: api.Notification,
/** /**
* Initialize notifications area. * A collection of observable notifications.
* *
* @since 4.9.0 * @since 4.9.0
* @constructor *
* @constructs wp.customize.Notifications
* @augments wp.customize.Values
*
* @param {object} options - Options. * @param {object} options - Options.
* @param {jQuery} [options.container] - Container element for notifications. This can be injected later. * @param {jQuery} [options.container] - Container element for notifications. This can be injected later.
* @param {boolean} [options.alt] - Whether alternative style should be used when rendering notifications. * @param {boolean} [options.alt] - Whether alternative style should be used when rendering notifications.
*
* @returns {void} * @returns {void}
* @this {wp.customize.Notifications}
*/ */
initialize: function( options ) { initialize: function( options ) {
var collection = this; var collection = this;
@ -181,7 +173,6 @@
* @param {object} args - Args. * @param {object} args - Args.
* @param {boolean} [args.sort=false] - Whether to return the notifications sorted. * @param {boolean} [args.sort=false] - Whether to return the notifications sorted.
* @return {Array.<wp.customize.Notification>} Notifications. * @return {Array.<wp.customize.Notification>} Notifications.
* @this {wp.customize.Notifications}
*/ */
get: function( args ) { get: function( args ) {
var collection = this, notifications, errorTypePriorities, params; var collection = this, notifications, errorTypePriorities, params;
@ -217,7 +208,6 @@
* *
* @since 4.9.0 * @since 4.9.0
* @returns {void} * @returns {void}
* @this {wp.customize.Notifications}
*/ */
render: function() { render: function() {
var collection = this, var collection = this,
@ -340,20 +330,7 @@
} }
}); });
/** api.Setting = api.Value.extend(/** @lends wp.customize.Setting.prototype */{
* A Customizer Setting.
*
* A setting is WordPress data (theme mod, option, menu, etc.) that the user can
* draft changes to in the Customizer.
*
* @see PHP class WP_Customize_Setting.
*
* @since 3.4.0
* @class
* @augments wp.customize.Value
* @augments wp.customize.Class
*/
api.Setting = api.Value.extend({
/** /**
* Default params. * Default params.
@ -367,7 +344,15 @@
}, },
/** /**
* Initialize. * A Customizer Setting.
*
* A setting is WordPress data (theme mod, option, menu, etc.) that the user can
* draft changes to in the Customizer.
*
* @see PHP class WP_Customize_Setting.
*
* @constructs wp.customize.Setting
* @augments wp.customize.Value
* *
* @since 3.4.0 * @since 3.4.0
* *
@ -448,6 +433,8 @@
/** /**
* Current change count. * Current change count.
* *
* @alias wp.customize._latestRevision
*
* @since 4.7.0 * @since 4.7.0
* @type {number} * @type {number}
* @protected * @protected
@ -457,6 +444,8 @@
/** /**
* Last revision that was saved. * Last revision that was saved.
* *
* @alias wp.customize._lastSavedRevision
*
* @since 4.7.0 * @since 4.7.0
* @type {number} * @type {number}
* @protected * @protected
@ -466,6 +455,8 @@
/** /**
* Latest revisions associated with the updated setting. * Latest revisions associated with the updated setting.
* *
* @alias wp.customize._latestSettingRevisions
*
* @since 4.7.0 * @since 4.7.0
* @type {object} * @type {object}
* @protected * @protected
@ -495,6 +486,8 @@
/** /**
* Get the dirty setting values. * Get the dirty setting values.
* *
* @alias wp.customize.dirtyValues
*
* @since 4.7.0 * @since 4.7.0
* @access public * @access public
* *
@ -526,6 +519,8 @@
/** /**
* Request updates to the changeset. * Request updates to the changeset.
* *
* @alias wp.customize.requestChangesetUpdate
*
* @since 4.7.0 * @since 4.7.0
* @access public * @access public
* *
@ -661,6 +656,8 @@
/** /**
* Watch all changes to Value properties, and bubble changes to parent Values instance * Watch all changes to Value properties, and bubble changes to parent Values instance
* *
* @alias wp.customize.utils.bubbleChildValueChanges
*
* @since 4.1.0 * @since 4.1.0
* *
* @param {wp.customize.Class} instance * @param {wp.customize.Class} instance
@ -679,6 +676,8 @@
/** /**
* Expand a panel, section, or control and focus on the first focusable element. * Expand a panel, section, or control and focus on the first focusable element.
* *
* @alias wp.customize~focus
*
* @since 4.1.0 * @since 4.1.0
* *
* @param {Object} [params] * @param {Object} [params]
@ -726,6 +725,8 @@
* *
* If a.priority() === b.priority(), then sort by their respective params.instanceNumber. * If a.priority() === b.priority(), then sort by their respective params.instanceNumber.
* *
* @alias wp.customize.utils.prioritySort
*
* @since 4.1.0 * @since 4.1.0
* *
* @param {(wp.customize.Panel|wp.customize.Section|wp.customize.Control)} a * @param {(wp.customize.Panel|wp.customize.Section|wp.customize.Control)} a
@ -743,6 +744,8 @@
/** /**
* Return whether the supplied Event object is for a keydown event but not the Enter key. * Return whether the supplied Event object is for a keydown event but not the Enter key.
* *
* @alias wp.customize.utils.isKeydownButNotEnterEvent
*
* @since 4.1.0 * @since 4.1.0
* *
* @param {jQuery.Event} event * @param {jQuery.Event} event
@ -755,6 +758,8 @@
/** /**
* Return whether the two lists of elements are the same and are in the same order. * Return whether the two lists of elements are the same and are in the same order.
* *
* @alias wp.customize.utils.areElementListsEqual
*
* @since 4.1.0 * @since 4.1.0
* *
* @param {Array|jQuery} listA * @param {Array|jQuery} listA
@ -781,6 +786,8 @@
* UI element, after an optional delay. If the user focuses the element * UI element, after an optional delay. If the user focuses the element
* before the delay passes, the reminder is canceled. * before the delay passes, the reminder is canceled.
* *
* @alias wp.customize.utils.highlightButton
*
* @since 4.9.0 * @since 4.9.0
* *
* @param {jQuery} button - The element to highlight. * @param {jQuery} button - The element to highlight.
@ -834,6 +841,8 @@
* *
* Same functionality as the `current_time( 'mysql', false )` function in PHP. * Same functionality as the `current_time( 'mysql', false )` function in PHP.
* *
* @alias wp.customize.utils.getCurrentTimestamp
*
* @since 4.9.0 * @since 4.9.0
* *
* @returns {int} Current timestamp. * @returns {int} Current timestamp.
@ -851,6 +860,8 @@
/** /**
* Get remaining time of when the date is set. * Get remaining time of when the date is set.
* *
* @alias wp.customize.utils.getRemainingTime
*
* @since 4.9.0 * @since 4.9.0
* *
* @param {string|int|Date} datetime - Date time or timestamp of the future date. * @param {string|int|Date} datetime - Date time or timestamp of the future date.
@ -876,6 +887,8 @@
* *
* @since 4.7.0 * @since 4.7.0
* *
* @ignore
*
* @returns {string|null} Normalized `transitionend` event name or null if CSS transitions are not supported. * @returns {string|null} Normalized `transitionend` event name or null if CSS transitions are not supported.
*/ */
normalizedTransitionendEventName = (function () { normalizedTransitionendEventName = (function () {
@ -897,15 +910,7 @@
} }
})(); })();
/** Container = api.Class.extend(/** @lends wp.customize~Container.prototype */{
* Base class for Panel and Section.
*
* @since 4.1.0
*
* @class
* @augments wp.customize.Class
*/
Container = api.Class.extend({
defaultActiveArguments: { duration: 'fast', completeCallback: $.noop }, defaultActiveArguments: { duration: 'fast', completeCallback: $.noop },
defaultExpandedArguments: { duration: 'fast', completeCallback: $.noop }, defaultExpandedArguments: { duration: 'fast', completeCallback: $.noop },
containerType: 'container', containerType: 'container',
@ -920,8 +925,15 @@
}, },
/** /**
* Base class for Panel and Section.
*
* @constructs wp.customize~Container
* @augments wp.customize.Class
*
* @since 4.1.0 * @since 4.1.0
* *
* @borrows wp.customize~focus as focus
*
* @param {string} id - The ID for the container. * @param {string} id - The ID for the container.
* @param {object} options - Object containing one property: params. * @param {object} options - Object containing one property: params.
* @param {string} options.title - Title shown when panel is collapsed and expanded. * @param {string} options.title - Title shown when panel is collapsed and expanded.
@ -999,7 +1011,6 @@
* *
* @since 4.9.0 * @since 4.9.0
* @returns {jQuery} Notification container element. * @returns {jQuery} Notification container element.
* @this {wp.customize.Control}
*/ */
getNotificationsContainerElement: function() { getNotificationsContainerElement: function() {
var container = this; var container = this;
@ -1305,9 +1316,8 @@
} ); } );
}, },
/** /*
* Bring the container into view and then expand this and bring it into view * is documented using @borrows in the constructor.
* @param {Object} [params]
*/ */
focus: focus, focus: focus,
@ -1370,13 +1380,7 @@
} }
}); });
/** api.Section = Container.extend(/** @lends wp.customize.Section.prototype */{
* @since 4.1.0
*
* @class
* @augments wp.customize.Class
*/
api.Section = Container.extend({
containerType: 'section', containerType: 'section',
containerParent: '#customize-theme-controls', containerParent: '#customize-theme-controls',
containerPaneParent: '.customize-pane-parent', containerPaneParent: '.customize-pane-parent',
@ -1393,6 +1397,9 @@
}, },
/** /**
* @constructs wp.customize.Section
* @augments wp.customize~Container
*
* @since 4.1.0 * @since 4.1.0
* *
* @param {string} id - The ID for the section. * @param {string} id - The ID for the section.
@ -1654,17 +1661,7 @@
} }
}); });
/** api.ThemesSection = api.Section.extend(/** @lends wp.customize.ThemesSection.prototype */{
* wp.customize.ThemesSection
*
* Custom section for themes that loads themes by category, and also
* handles the theme-details view rendering and navigation.
*
* @constructor
* @augments wp.customize.Section
* @augments wp.customize.Container
*/
api.ThemesSection = api.Section.extend({
currentTheme: '', currentTheme: '',
overlay: '', overlay: '',
template: '', template: '',
@ -1683,7 +1680,13 @@
updateCountDebounced: null, updateCountDebounced: null,
/** /**
* Initialize. * wp.customize.ThemesSection
*
* Custom section for themes that loads themes by category, and also
* handles the theme-details view rendering and navigation.
*
* @constructs wp.customize.ThemesSection
* @augments wp.customize.Section
* *
* @since 4.9.0 * @since 4.9.0
* *
@ -2627,22 +2630,16 @@
} }
}); });
api.OuterSection = api.Section.extend(/** @lends wp.customize.OuterSection.prototype */{
/** /**
* Class wp.customize.OuterSection. * Class wp.customize.OuterSection.
* *
* Creates section outside of the sidebar, there is no ui to trigger collapse/expand so * Creates section outside of the sidebar, there is no ui to trigger collapse/expand so
* it would require custom handling. * it would require custom handling.
* *
* @since 4.9 * @constructs wp.customize.OuterSection
*
* @constructor
* @augments wp.customize.Section * @augments wp.customize.Section
* @augments wp.customize.Container
*/
api.OuterSection = api.Section.extend({
/**
* Initialize.
* *
* @since 4.9.0 * @since 4.9.0
* *
@ -2746,16 +2743,13 @@
} }
}); });
/** api.Panel = Container.extend(/** @lends wp.customize.Panel.prototype */{
* @since 4.1.0
*
* @class
* @augments wp.customize.Class
*/
api.Panel = Container.extend({
containerType: 'panel', containerType: 'panel',
/** /**
* @constructs wp.customize.Panel
* @augments wp.customize~Container
*
* @since 4.1.0 * @since 4.1.0
* *
* @param {string} id - The ID for the panel. * @param {string} id - The ID for the panel.
@ -3020,19 +3014,15 @@
} }
}); });
api.ThemesPanel = api.Panel.extend(/** @lends wp.customize.ThemsPanel.prototype */{
/** /**
* Class wp.customize.ThemesPanel. * Class wp.customize.ThemesPanel.
* *
* Custom section for themes that displays without the customize preview. * Custom section for themes that displays without the customize preview.
* *
* @constructor * @constructs wp.customize.ThemesPanel
* @augments wp.customize.Panel * @augments wp.customize.Panel
* @augments wp.customize.Container
*/
api.ThemesPanel = api.Panel.extend({
/**
* Initialize.
* *
* @since 4.9.0 * @since 4.9.0
* *
@ -3451,17 +3441,7 @@
} }
}); });
/** api.Control = api.Class.extend(/** @lends wp.customize.Control.prototype */{
* A Customizer Control.
*
* A control provides a UI element that allows a user to modify a Customizer Setting.
*
* @see PHP class WP_Customize_Control.
*
* @class
* @augments wp.customize.Class
*/
api.Control = api.Class.extend({
defaultActiveArguments: { duration: 'fast', completeCallback: $.noop }, defaultActiveArguments: { duration: 'fast', completeCallback: $.noop },
/** /**
@ -3478,7 +3458,19 @@
}, },
/** /**
* Initialize. * A Customizer Control.
*
* A control provides a UI element that allows a user to modify a Customizer Setting.
*
* @see PHP class WP_Customize_Control.
*
* @constructs wp.customize.Control
* @augments wp.customize.Class
*
* @borrows wp.customize~focus as this#focus
* @borrows wp.customize~Container#activate as this#activate
* @borrows wp.customize~Container#deactivate as this#deactivate
* @borrows wp.customize~Container#_toggleActive as this#_toggleActive
* *
* @param {string} id - Unique identifier for the control instance. * @param {string} id - Unique identifier for the control instance.
* @param {object} options - Options hash for the control instance. * @param {object} options - Options hash for the control instance.
@ -3744,7 +3736,6 @@
* *
* @since 4.6.0 * @since 4.6.0
* @returns {jQuery} Setting validation message element. * @returns {jQuery} Setting validation message element.
* @this {wp.customize.Control}
*/ */
getNotificationsContainerElement: function() { getNotificationsContainerElement: function() {
var control = this, controlTitle, notificationsContainer; var control = this, controlTitle, notificationsContainer;
@ -3888,9 +3879,8 @@
api.section( this.section() ).expand( params ); api.section( this.section() ).expand( params );
}, },
/** /*
* Bring the containing section and panel into view and then * Documented using @borrows in the constructor.
* this control into view, focusing on the first input.
*/ */
focus: focus, focus: focus,
@ -3934,30 +3924,18 @@
return this.onChangeActive( active, this.defaultActiveArguments ); return this.onChangeActive( active, this.defaultActiveArguments );
}, },
/** /*
* Shorthand way to enable the active state. * Documented using @borrows in the constructor
*
* @since 4.1.0
*
* @param {Object} [params]
* @returns {Boolean} false if already active
*/ */
activate: Container.prototype.activate, activate: Container.prototype.activate,
/** /*
* Shorthand way to disable the active state. * Documented using @borrows in the constructor
*
* @since 4.1.0
*
* @param {Object} [params]
* @returns {Boolean} false if already inactive
*/ */
deactivate: Container.prototype.deactivate, deactivate: Container.prototype.deactivate,
/** /*
* Re-use _toggleActive from Container class. * Documented using @borrows in the constructor
*
* @access private
*/ */
_toggleActive: Container.prototype._toggleActive, _toggleActive: Container.prototype._toggleActive,
@ -4131,11 +4109,10 @@
/** /**
* A colorpicker control. * A colorpicker control.
* *
* @class * @class wp.customize.ColorControl
* @augments wp.customize.Control * @augments wp.customize.Control
* @augments wp.customize.Class
*/ */
api.ColorControl = api.Control.extend({ api.ColorControl = api.Control.extend(/** @lends wp.customize.ColorControl.prototype */{
ready: function() { ready: function() {
var control = this, var control = this,
isHueSlider = this.params.mode === 'hue', isHueSlider = this.params.mode === 'hue',
@ -4195,11 +4172,10 @@
/** /**
* A control that implements the media modal. * A control that implements the media modal.
* *
* @class * @class wp.customize.MediaControl
* @augments wp.customize.Control * @augments wp.customize.Control
* @augments wp.customize.Class
*/ */
api.MediaControl = api.Control.extend({ api.MediaControl = api.Control.extend(/** @lends wp.customize.MediaControl.prototype */{
/** /**
* When the control's DOM structure is ready, * When the control's DOM structure is ready,
@ -4384,12 +4360,10 @@
/** /**
* An upload control, which utilizes the media modal. * An upload control, which utilizes the media modal.
* *
* @class * @class wp.customize.UploadControl
* @augments wp.customize.MediaControl * @augments wp.customize.MediaControl
* @augments wp.customize.Control
* @augments wp.customize.Class
*/ */
api.UploadControl = api.MediaControl.extend({ api.UploadControl = api.MediaControl.extend(/** @lends wp.customize.UploadControl.prototype */{
/** /**
* Callback handler for when an attachment is selected in the media modal. * Callback handler for when an attachment is selected in the media modal.
@ -4428,13 +4402,10 @@
* This control no longer needs to do anything more * This control no longer needs to do anything more
* than what the upload control does in JS. * than what the upload control does in JS.
* *
* @class * @class wp.customize.ImageControl
* @augments wp.customize.UploadControl * @augments wp.customize.UploadControl
* @augments wp.customize.MediaControl
* @augments wp.customize.Control
* @augments wp.customize.Class
*/ */
api.ImageControl = api.UploadControl.extend({ api.ImageControl = api.UploadControl.extend(/** @lends wp.customize.ImageControl.prototype */{
// @deprecated // @deprecated
thumbnailSrc: function() {} thumbnailSrc: function() {}
}); });
@ -4442,13 +4413,10 @@
/** /**
* A control for uploading background images. * A control for uploading background images.
* *
* @class * @class wp.customize.BackgroundControl
* @augments wp.customize.UploadControl * @augments wp.customize.UploadControl
* @augments wp.customize.MediaControl
* @augments wp.customize.Control
* @augments wp.customize.Class
*/ */
api.BackgroundControl = api.UploadControl.extend({ api.BackgroundControl = api.UploadControl.extend(/** @lends wp.customize.BackgroundControl.prototype */{
/** /**
* When the control's DOM structure is ready, * When the control's DOM structure is ready,
@ -4479,11 +4447,10 @@
* *
* @since 4.7.0 * @since 4.7.0
* *
* @class * @class wp.customize.BackgroundPositionControl
* @augments wp.customize.Control * @augments wp.customize.Control
* @augments wp.customize.Class
*/ */
api.BackgroundPositionControl = api.Control.extend( { api.BackgroundPositionControl = api.Control.extend(/** @lends wp.customize.BackgroundPositionControl.prototype */{
/** /**
* Set up control UI once embedded in DOM and settings are created. * Set up control UI once embedded in DOM and settings are created.
@ -4518,12 +4485,10 @@
/** /**
* A control for selecting and cropping an image. * A control for selecting and cropping an image.
* *
* @class * @class wp.customize.CroppedImageControl
* @augments wp.customize.MediaControl * @augments wp.customize.MediaControl
* @augments wp.customize.Control
* @augments wp.customize.Class
*/ */
api.CroppedImageControl = api.MediaControl.extend({ api.CroppedImageControl = api.MediaControl.extend(/** @lends wp.customize.CroppedImageControl.prototype */{
/** /**
* Open the media modal to the library state. * Open the media modal to the library state.
@ -4720,13 +4685,10 @@
/** /**
* A control for selecting and cropping Site Icons. * A control for selecting and cropping Site Icons.
* *
* @class * @class wp.customize.SiteIconControl
* @augments wp.customize.CroppedImageControl * @augments wp.customize.CroppedImageControl
* @augments wp.customize.MediaControl
* @augments wp.customize.Control
* @augments wp.customize.Class
*/ */
api.SiteIconControl = api.CroppedImageControl.extend({ api.SiteIconControl = api.CroppedImageControl.extend(/** @lends wp.customize.SiteIconControl.prototype */{
/** /**
* Create a media modal select frame, and store it so the instance can be reused when needed. * Create a media modal select frame, and store it so the instance can be reused when needed.
@ -4841,11 +4803,10 @@
}); });
/** /**
* @class * @class wp.customize.HeaderControl
* @augments wp.customize.Control * @augments wp.customize.Control
* @augments wp.customize.Class
*/ */
api.HeaderControl = api.Control.extend({ api.HeaderControl = api.Control.extend(/** @lends wp.customize.HeaderControl.prototype */{
ready: function() { ready: function() {
this.btnRemove = $('#customize-control-header_image .actions .remove'); this.btnRemove = $('#customize-control-header_image .actions .remove');
this.btnNew = $('#customize-control-header_image .actions .new'); this.btnNew = $('#customize-control-header_image .actions .new');
@ -5111,11 +5072,10 @@
/** /**
* wp.customize.ThemeControl * wp.customize.ThemeControl
* *
* @constructor * @class wp.customize.ThemeControl
* @augments wp.customize.Control * @augments wp.customize.Control
* @augments wp.customize.Class
*/ */
api.ThemeControl = api.Control.extend({ api.ThemeControl = api.Control.extend(/** @lends wp.customize.ThemeControl.prototype */{
touchDrag: false, touchDrag: false,
screenshotRendered: false, screenshotRendered: false,
@ -5263,11 +5223,10 @@
* *
* @since 4.9.0 * @since 4.9.0
* *
* @constructor * @class wp.customize.CodeEditorControl
* @augments wp.customize.Control * @augments wp.customize.Control
* @augments wp.customize.Class
*/ */
api.CodeEditorControl = api.Control.extend({ api.CodeEditorControl = api.Control.extend(/** @lends wp.customize.CodeEditorControl.prototype */{
/** /**
* Initialize. * Initialize.
@ -5584,11 +5543,10 @@
* Class wp.customize.DateTimeControl. * Class wp.customize.DateTimeControl.
* *
* @since 4.9.0 * @since 4.9.0
* @constructor * @class wp.customize.DateTimeControl
* @augments wp.customize.Control * @augments wp.customize.Control
* @augments wp.customize.Class
*/ */
api.DateTimeControl = api.Control.extend({ api.DateTimeControl = api.Control.extend(/** @lends wp.customize.DateTimeControl.prototype */{
/** /**
* Initialize behaviors. * Initialize behaviors.
@ -5939,11 +5897,10 @@
* Class PreviewLinkControl. * Class PreviewLinkControl.
* *
* @since 4.9.0 * @since 4.9.0
* @constructor * @class wp.customize.PreviewLinkControl
* @augments wp.customize.Control * @augments wp.customize.Control
* @augments wp.customize.Class
*/ */
api.PreviewLinkControl = api.Control.extend({ api.PreviewLinkControl = api.Control.extend(/** @lends wp.customize.PreviewLinkControl.prototype */{
defaults: _.extend( {}, api.Control.prototype.defaults, { defaults: _.extend( {}, api.Control.prototype.defaults, {
templateId: 'customize-preview-link-control' templateId: 'customize-preview-link-control'
@ -6057,19 +6014,25 @@
} }
}); });
// Change objects contained within the main customize object to Settings. /**
* Change objects contained within the main customize object to Settings.
*
* @alias wp.customize.defaultConstructor
*/
api.defaultConstructor = api.Setting; api.defaultConstructor = api.Setting;
/** /**
* Callback for resolved controls. * Callback for resolved controls.
* *
* @callback deferredControlsCallback * @callback wp.customize.deferredControlsCallback
* @param {wp.customize.Control[]} Resolved controls. * @param {wp.customize.Control[]} controls Resolved controls.
*/ */
/** /**
* Collection of all registered controls. * Collection of all registered controls.
* *
* @alias wp.customize.control
*
* @since 3.4.0 * @since 3.4.0
* *
* @type {Function} * @type {Function}
@ -6122,13 +6085,15 @@
/** /**
* Callback for resolved sections. * Callback for resolved sections.
* *
* @callback deferredSectionsCallback * @callback wp.customize.deferredSectionsCallback
* @param {wp.customize.Section[]} Resolved sections. * @param {wp.customize.Section[]} sections Resolved sections.
*/ */
/** /**
* Collection of all registered sections. * Collection of all registered sections.
* *
* @alias wp.customize.section
*
* @since 3.4.0 * @since 3.4.0
* *
* @type {Function} * @type {Function}
@ -6154,13 +6119,15 @@
/** /**
* Callback for resolved panels. * Callback for resolved panels.
* *
* @callback deferredPanelsCallback * @callback wp.customize.deferredPanelsCallback
* @param {wp.customize.Panel[]} Resolved panels. * @param {wp.customize.Panel[]} panels Resolved panels.
*/ */
/** /**
* Collection of all registered panels. * Collection of all registered panels.
* *
* @alias wp.customize.panel
*
* @since 4.0.0 * @since 4.0.0
* *
* @type {Function} * @type {Function}
@ -6186,13 +6153,15 @@
/** /**
* Callback for resolved notifications. * Callback for resolved notifications.
* *
* @callback deferredNotificationsCallback * @callback wp.customize.deferredNotificationsCallback
* @param {wp.customize.Notification[]} Resolved notifications. * @param {wp.customize.Notification[]} notifications Resolved notifications.
*/ */
/** /**
* Collection of all global notifications. * Collection of all global notifications.
* *
* @alias wp.customize.notifications
*
* @since 4.9.0 * @since 4.9.0
* *
* @type {Function} * @type {Function}
@ -6223,20 +6192,15 @@
*/ */
api.notifications = new api.Notifications(); api.notifications = new api.Notifications();
api.PreviewFrame = api.Messenger.extend(/** @lends wp.customize.PreviewFrame.prototype */{
sensitivity: null, // Will get set to api.settings.timeouts.previewFrameSensitivity.
/** /**
* An object that fetches a preview in the background of the document, which * An object that fetches a preview in the background of the document, which
* allows for seamless replacement of an existing preview. * allows for seamless replacement of an existing preview.
* *
* @class * @constructs wp.customize.PreviewFrame
* @augments wp.customize.Messenger * @augments wp.customize.Messenger
* @augments wp.customize.Class
* @mixes wp.customize.Events
*/
api.PreviewFrame = api.Messenger.extend({
sensitivity: null, // Will get set to api.settings.timeouts.previewFrameSensitivity.
/**
* Initialize the PreviewFrame.
* *
* @param {object} params.container * @param {object} params.container
* @param {object} params.previewUrl * @param {object} params.previewUrl
@ -6454,6 +6418,8 @@
/** /**
* Set the document title of the customizer. * Set the document title of the customizer.
* *
* @alias wp.customize.setDocumentTitle
*
* @since 4.1.0 * @since 4.1.0
* *
* @param {string} documentTitle * @param {string} documentTitle
@ -6466,16 +6432,13 @@
api.trigger( 'title', title ); api.trigger( 'title', title );
}; };
/** api.Previewer = api.Messenger.extend(/** @lends wp.customize.Previewer.prototype */{
* @class
* @augments wp.customize.Messenger
* @augments wp.customize.Class
* @mixes wp.customize.Events
*/
api.Previewer = api.Messenger.extend({
refreshBuffer: null, // Will get set to api.settings.timeouts.windowRefresh. refreshBuffer: null, // Will get set to api.settings.timeouts.windowRefresh.
/** /**
* @constructs wp.customize.Previewer
* @augments wp.customize.Messenger
*
* @param {array} params.allowedUrls * @param {array} params.allowedUrls
* @param {string} params.container A selector or jQuery element for the preview * @param {string} params.container A selector or jQuery element for the preview
* frame to be placed. * frame to be placed.
@ -6929,6 +6892,8 @@
* *
* Add notifications to the settings and focus on the first control that has an invalid setting. * Add notifications to the settings and focus on the first control that has an invalid setting.
* *
* @alias wp.customize._handleSettingValidities
*
* @since 4.6.0 * @since 4.6.0
* @private * @private
* *
@ -7004,6 +6969,8 @@
/** /**
* Find all controls associated with the given settings. * Find all controls associated with the given settings.
* *
* @alias wp.customize.findControlsForSettings
*
* @since 4.6.0 * @since 4.6.0
* @param {string[]} settingIds Setting IDs. * @param {string[]} settingIds Setting IDs.
* @returns {object<string, wp.customize.Control>} Mapping setting ids to arrays of controls. * @returns {object<string, wp.customize.Control>} Mapping setting ids to arrays of controls.
@ -7025,6 +6992,8 @@
/** /**
* Sort panels, sections, controls by priorities. Hide empty sections and panels. * Sort panels, sections, controls by priorities. Hide empty sections and panels.
* *
* @alias wp.customize.reflowPaneContents
*
* @since 4.1.0 * @since 4.1.0
*/ */
api.reflowPaneContents = _.bind( function () { api.reflowPaneContents = _.bind( function () {
@ -7389,13 +7358,17 @@
} }
}); });
// Initialize Previewer /**
* Initialize Previewer
*
* @alias wp.customize.previewer
*/
api.previewer = new api.Previewer({ api.previewer = new api.Previewer({
container: '#customize-preview', container: '#customize-preview',
form: '#customize-controls', form: '#customize-controls',
previewUrl: api.settings.url.preview, previewUrl: api.settings.url.preview,
allowedUrls: api.settings.url.allowed allowedUrls: api.settings.url.allowed
}, { },/** @lends wp.customize.previewer */{
nonce: api.settings.nonce, nonce: api.settings.nonce,
@ -8098,15 +8071,7 @@
*/ */
( function checkAndDisplayLockNotice() { ( function checkAndDisplayLockNotice() {
/** var LockedNotification = api.OverlayNotification.extend(/** @lends wp.customize~LockedNotification.prototype */{
* A notification that is displayed in a full-screen overlay with information about the locked changeset.
*
* @since 4.9.0
* @class
* @augments wp.customize.Notification
* @augments wp.customize.OverlayNotification
*/
var LockedNotification = api.OverlayNotification.extend({
/** /**
* Template ID. * Template ID.
@ -8123,7 +8088,10 @@
lockUser: null, lockUser: null,
/** /**
* Initialize. * A notification that is displayed in a full-screen overlay with information about the locked changeset.
*
* @constructs wp.customize~LockedNotification
* @augments wp.customize.OverlayNotification
* *
* @since 4.9.0 * @since 4.9.0
* *

101
src/wp-admin/js/customize-nav-menus.js
View File

@ -13,6 +13,9 @@
this.jQueryExtensions(); this.jQueryExtensions();
}; };
/**
* @namespace wp.customize.Menus
*/
api.Menus = api.Menus || {}; api.Menus = api.Menus || {};
// Link settings. // Link settings.
@ -35,6 +38,8 @@
* Newly-created Nav Menus and Nav Menu Items have negative integer IDs which * Newly-created Nav Menus and Nav Menu Items have negative integer IDs which
* serve as placeholders until Save & Publish happens. * serve as placeholders until Save & Publish happens.
* *
* @alias wp.customize.Menus.generatePlaceholderAutoIncrementId
*
* @return {number} * @return {number}
*/ */
api.Menus.generatePlaceholderAutoIncrementId = function() { api.Menus.generatePlaceholderAutoIncrementId = function() {
@ -46,7 +51,7 @@
* *
* A single available menu item model. See PHP's WP_Customize_Nav_Menu_Item_Setting class. * A single available menu item model. See PHP's WP_Customize_Nav_Menu_Item_Setting class.
* *
* @constructor * @class wp.customize.Menus.AvailableItemModel
* @augments Backbone.Model * @augments Backbone.Model
*/ */
api.Menus.AvailableItemModel = Backbone.Model.extend( $.extend( api.Menus.AvailableItemModel = Backbone.Model.extend( $.extend(
@ -61,10 +66,10 @@
* *
* Collection for available menu item models. * Collection for available menu item models.
* *
* @constructor * @class wp.customize.Menus.AvailableItemCollection
* @augments Backbone.Model * @augments Backbone.Collection
*/ */
api.Menus.AvailableItemCollection = Backbone.Collection.extend({ api.Menus.AvailableItemCollection = Backbone.Collection.extend(/** @lends wp.customize.Menus.AvailableItemCollection.prototype */{
model: api.Menus.AvailableItemModel, model: api.Menus.AvailableItemModel,
sort_key: 'order', sort_key: 'order',
@ -84,7 +89,7 @@
* Insert a new `auto-draft` post. * Insert a new `auto-draft` post.
* *
* @since 4.7.0 * @since 4.7.0
* @access public * @alias wp.customize.Menus.insertAutoDraftPost
* *
* @param {object} params - Parameters for the draft post to create. * @param {object} params - Parameters for the draft post to create.
* @param {string} params.post_type - Post type to add. * @param {string} params.post_type - Post type to add.
@ -141,16 +146,7 @@
return deferred.promise(); return deferred.promise();
}; };
/** api.Menus.AvailableMenuItemsPanelView = wp.Backbone.View.extend(/** @lends wp.customize.Menus.AvailableMenuItemsPanelView.prototype */{
* wp.customize.Menus.AvailableMenuItemsPanelView
*
* View class for the available menu items panel.
*
* @constructor
* @augments wp.Backbone.View
* @augments Backbone.View
*/
api.Menus.AvailableMenuItemsPanelView = wp.Backbone.View.extend({
el: '#available-menu-items', el: '#available-menu-items',
@ -181,6 +177,14 @@
loading: false, loading: false,
addingNew: false, addingNew: false,
/**
* wp.customize.Menus.AvailableMenuItemsPanelView
*
* View class for the available menu items panel.
*
* @constructs wp.customize.Menus.AvailableMenuItemsPanelView
* @augments wp.Backbone.View
*/
initialize: function() { initialize: function() {
var self = this; var self = this;
@ -753,10 +757,10 @@
* Customizer panel for menus. This is used only for screen options management. * Customizer panel for menus. This is used only for screen options management.
* Note that 'menus' must match the WP_Customize_Menu_Panel::$type. * Note that 'menus' must match the WP_Customize_Menu_Panel::$type.
* *
* @constructor * @class wp.customize.Menus.MenusPanel
* @augments wp.customize.Panel * @augments wp.customize.Panel
*/ */
api.Menus.MenusPanel = api.Panel.extend({ api.Menus.MenusPanel = api.Panel.extend(/** @lends wp.customize.Menus.MenusPanel.prototype */{
attachEvents: function() { attachEvents: function() {
api.Panel.prototype.attachEvents.call( this ); api.Panel.prototype.attachEvents.call( this );
@ -885,10 +889,10 @@
* Customizer section for menus. This is used only for lazy-loading child controls. * Customizer section for menus. This is used only for lazy-loading child controls.
* Note that 'nav_menu' must match the WP_Customize_Menu_Section::$type. * Note that 'nav_menu' must match the WP_Customize_Menu_Section::$type.
* *
* @constructor * @class wp.customize.Menus.MenuSection
* @augments wp.customize.Section * @augments wp.customize.Section
*/ */
api.Menus.MenuSection = api.Section.extend({ api.Menus.MenuSection = api.Section.extend(/** @lends wp.customize.Menus.MenuSection.prototype */{
/** /**
* Initialize. * Initialize.
@ -1212,10 +1216,10 @@
* *
* Customizer section for new menus. * Customizer section for new menus.
* *
* @constructor * @class wp.customize.Menus.NewMenuSection
* @augments wp.customize.Section * @augments wp.customize.Section
*/ */
api.Menus.NewMenuSection = api.Section.extend({ api.Menus.NewMenuSection = api.Section.extend(/** @lends wp.customize.Menus.NewMenuSection.prototype */{
/** /**
* Add behaviors for the accordion section. * Add behaviors for the accordion section.
@ -1451,10 +1455,10 @@
* Customizer control for menu locations (rendered as a <select>). * Customizer control for menu locations (rendered as a <select>).
* Note that 'nav_menu_location' must match the WP_Customize_Nav_Menu_Location_Control::$type. * Note that 'nav_menu_location' must match the WP_Customize_Nav_Menu_Location_Control::$type.
* *
* @constructor * @class wp.customize.Menus.MenuLocationControl
* @augments wp.customize.Control * @augments wp.customize.Control
*/ */
api.Menus.MenuLocationControl = api.Control.extend({ api.Menus.MenuLocationControl = api.Control.extend(/** @lends wp.customize.Menus.MenuLocationControl.prototype */{
initialize: function( id, options ) { initialize: function( id, options ) {
var control = this, var control = this,
matches = id.match( /^nav_menu_locations\[(.+?)]/ ); matches = id.match( /^nav_menu_locations\[(.+?)]/ );
@ -1529,19 +1533,18 @@
} }
}); });
api.Menus.MenuItemControl = api.Control.extend(/** @lends wp.customize.Menus.MenuItemControl.prototype */{
/** /**
* wp.customize.Menus.MenuItemControl * wp.customize.Menus.MenuItemControl
* *
* Customizer control for menu items. * Customizer control for menu items.
* Note that 'menu_item' must match the WP_Customize_Menu_Item_Control::$type. * Note that 'menu_item' must match the WP_Customize_Menu_Item_Control::$type.
* *
* @constructor * @constructs wp.customize.Menus.MenuItemControl
* @augments wp.customize.Control * @augments wp.customize.Control
*/ *
api.Menus.MenuItemControl = api.Control.extend({ * @inheritDoc
/**
* @inheritdoc
*/ */
initialize: function( id, options ) { initialize: function( id, options ) {
var control = this; var control = this;
@ -2324,10 +2327,10 @@
* *
* Customizer control for a nav menu's name. * Customizer control for a nav menu's name.
* *
* @constructor * @class wp.customize.Menus.MenuNameControl
* @augments wp.customize.Control * @augments wp.customize.Control
*/ */
api.Menus.MenuNameControl = api.Control.extend({ api.Menus.MenuNameControl = api.Control.extend(/** @lends wp.customize.Menus.MenuNameControl.prototype */{
ready: function() { ready: function() {
var control = this; var control = this;
@ -2364,10 +2367,10 @@
* Customizer control for a nav menu's locations. * Customizer control for a nav menu's locations.
* *
* @since 4.9.0 * @since 4.9.0
* @constructor * @class wp.customize.Menus.MenuLocationsControl
* @augments wp.customize.Control * @augments wp.customize.Control
*/ */
api.Menus.MenuLocationsControl = api.Control.extend({ api.Menus.MenuLocationsControl = api.Control.extend(/** @lends wp.customize.Menus.MenuLocationsControl.prototype */{
/** /**
* Set up the control. * Set up the control.
@ -2437,10 +2440,10 @@
* *
* Customizer control for a nav menu's auto add. * Customizer control for a nav menu's auto add.
* *
* @constructor * @class wp.customize.Menus.MenuAutoAddControl
* @augments wp.customize.Control * @augments wp.customize.Control
*/ */
api.Menus.MenuAutoAddControl = api.Control.extend({ api.Menus.MenuAutoAddControl = api.Control.extend(/** @lends wp.customize.Menus.MenuAutoAddControl.prototype */{
ready: function() { ready: function() {
var control = this, var control = this,
@ -2490,10 +2493,10 @@
* Customizer control for menus. * Customizer control for menus.
* Note that 'nav_menu' must match the WP_Menu_Customize_Control::$type * Note that 'nav_menu' must match the WP_Menu_Customize_Control::$type
* *
* @constructor * @class wp.customize.Menus.MenuControl
* @augments wp.customize.Control * @augments wp.customize.Control
*/ */
api.Menus.MenuControl = api.Control.extend({ api.Menus.MenuControl = api.Control.extend(/** @lends wp.customize.Menus.MenuControl.prototype */{
/** /**
* Set up the control. * Set up the control.
*/ */
@ -3021,22 +3024,18 @@
} }
} ); } );
api.Menus.NewMenuControl = api.Control.extend(/** @lends wp.customize.Menus.NewMenuControl.prototype */{
/** /**
* wp.customize.Menus.NewMenuControl * wp.customize.Menus.NewMenuControl
* *
* Customizer control for creating new menus and handling deletion of existing menus. * Customizer control for creating new menus and handling deletion of existing menus.
* Note that 'new_menu' must match the WP_Customize_New_Menu_Control::$type. * Note that 'new_menu' must match the WP_Customize_New_Menu_Control::$type.
* *
* @constructor * @constructs wp.customize.Menus.NewMenuControl
* @augments wp.customize.Control * @augments wp.customize.Control
* @deprecated 4.9.0 This class is no longer used due to new menu creation UX.
*/
api.Menus.NewMenuControl = api.Control.extend({
/**
* Initialize.
* *
* @deprecated 4.9.0 * @deprecated 4.9.0 This class is no longer used due to new menu creation UX.
*/ */
initialize: function() { initialize: function() {
if ( 'undefined' !== typeof console && console.warn ) { if ( 'undefined' !== typeof console && console.warn ) {
@ -3166,6 +3165,8 @@
* When customize_save comes back with a success, make sure any inserted * When customize_save comes back with a success, make sure any inserted
* nav menus and items are properly re-added with their newly-assigned IDs. * nav menus and items are properly re-added with their newly-assigned IDs.
* *
* @alias wp.customize.Menus.applySavedData
*
* @param {object} data * @param {object} data
* @param {array} data.nav_menu_updates * @param {array} data.nav_menu_updates
* @param {array} data.nav_menu_item_updates * @param {array} data.nav_menu_item_updates
@ -3396,6 +3397,8 @@
/** /**
* Focus a menu item control. * Focus a menu item control.
* *
* @alias wp.customize.Menus.focusMenuItemControl
*
* @param {string} menuItemId * @param {string} menuItemId
*/ */
api.Menus.focusMenuItemControl = function( menuItemId ) { api.Menus.focusMenuItemControl = function( menuItemId ) {
@ -3408,6 +3411,8 @@
/** /**
* Get the control for a given menu. * Get the control for a given menu.
* *
* @alias wp.customize.Menus.getMenuControl
*
* @param menuId * @param menuId
* @return {wp.customize.controlConstructor.menus[]} * @return {wp.customize.controlConstructor.menus[]}
*/ */
@ -3418,6 +3423,8 @@
/** /**
* Given a menu item ID, get the control associated with it. * Given a menu item ID, get the control associated with it.
* *
* @alias wp.customize.Menus.getMenuItemControl
*
* @param {string} menuItemId * @param {string} menuItemId
* @return {object|null} * @return {object|null}
*/ */
@ -3426,6 +3433,8 @@
}; };
/** /**
* @alias wp.customize.Menus~menuItemIdToSettingId
*
* @param {String} menuItemId * @param {String} menuItemId
*/ */
function menuItemIdToSettingId( menuItemId ) { function menuItemIdToSettingId( menuItemId ) {
@ -3436,6 +3445,8 @@
* Apply sanitize_text_field()-like logic to the supplied name, returning a * Apply sanitize_text_field()-like logic to the supplied name, returning a
* "unnammed" fallback string if the name is then empty. * "unnammed" fallback string if the name is then empty.
* *
* @alias wp.customize.Menus~displayNavMenuName
*
* @param {string} name * @param {string} name
* @returns {string} * @returns {string}
*/ */

119
src/wp-admin/js/customize-widgets.js
View File

@ -7,6 +7,9 @@
var api = wp.customize, var api = wp.customize,
l10n; l10n;
/**
* @namespace wp.customize.Widgets
*/
api.Widgets = api.Widgets || {}; api.Widgets = api.Widgets || {};
api.Widgets.savedWidgetIds = {}; api.Widgets.savedWidgetIds = {};
@ -19,10 +22,10 @@
* *
* A single widget model. * A single widget model.
* *
* @constructor * @class wp.customize.Widgets.WidgetModel
* @augments Backbone.Model * @augments Backbone.Model
*/ */
api.Widgets.WidgetModel = Backbone.Model.extend({ api.Widgets.WidgetModel = Backbone.Model.extend(/** @lends wp.customize.Widgets.WidgetModel.prototype */{
id: null, id: null,
temp_id: null, temp_id: null,
classname: null, classname: null,
@ -45,10 +48,10 @@
* *
* Collection for widget models. * Collection for widget models.
* *
* @constructor * @class wp.customize.Widgets.WidgetCollection
* @augments Backbone.Model * @augments Backbone.Collection
*/ */
api.Widgets.WidgetCollection = Backbone.Collection.extend({ api.Widgets.WidgetCollection = Backbone.Collection.extend(/** @lends wp.customize.Widgets.WidgetCollection.prototype */{
model: api.Widgets.WidgetModel, model: api.Widgets.WidgetModel,
// Controls searching on the current widget collection // Controls searching on the current widget collection
@ -103,10 +106,10 @@
* *
* A single sidebar model. * A single sidebar model.
* *
* @constructor * @class wp.customize.Widgets.SidebarModel
* @augments Backbone.Model * @augments Backbone.Model
*/ */
api.Widgets.SidebarModel = Backbone.Model.extend({ api.Widgets.SidebarModel = Backbone.Model.extend(/** @lends wp.customize.Widgets.SidebarModel.prototype */{
after_title: null, after_title: null,
after_widget: null, after_widget: null,
before_title: null, before_title: null,
@ -123,24 +126,15 @@
* *
* Collection for sidebar models. * Collection for sidebar models.
* *
* @constructor * @class wp.customize.Widgets.SidebarCollection
* @augments Backbone.Collection * @augments Backbone.Collection
*/ */
api.Widgets.SidebarCollection = Backbone.Collection.extend({ api.Widgets.SidebarCollection = Backbone.Collection.extend(/** @lends wp.customize.Widgets.SidebarCollection.prototype */{
model: api.Widgets.SidebarModel model: api.Widgets.SidebarModel
}); });
api.Widgets.registeredSidebars = new api.Widgets.SidebarCollection( api.Widgets.data.registeredSidebars ); api.Widgets.registeredSidebars = new api.Widgets.SidebarCollection( api.Widgets.data.registeredSidebars );
/** api.Widgets.AvailableWidgetsPanelView = wp.Backbone.View.extend(/** @lends wp.customize.Widgets.AvailableWidgetsPanelView.prototype */{
* wp.customize.Widgets.AvailableWidgetsPanelView
*
* View class for the available widgets panel.
*
* @constructor
* @augments wp.Backbone.View
* @augments Backbone.View
*/
api.Widgets.AvailableWidgetsPanelView = wp.Backbone.View.extend({
el: '#available-widgets', el: '#available-widgets',
@ -162,6 +156,12 @@
$clearResults: null, $clearResults: null,
searchMatchesCount: null, searchMatchesCount: null,
/**
* View class for the available widgets panel.
*
* @constructs wp.customize.Widgets.AvailableWidgetsPanelView
* @augments wp.Backbone.View
*/
initialize: function() { initialize: function() {
var self = this; var self = this;
@ -197,7 +197,9 @@
api.previewer.bind( 'url', this.close ); api.previewer.bind( 'url', this.close );
}, },
// Performs a search and handles selected widget /**
* Performs a search and handles selected widget.
*/
search: function( event ) { search: function( event ) {
var firstVisible; var firstVisible;
@ -242,12 +244,16 @@
} }
}, },
// Update the count of the available widgets that have the `search_matched` attribute. /**
* Updates the count of the available widgets that have the `search_matched` attribute.
*/
updateSearchMatchesCount: function() { updateSearchMatchesCount: function() {
this.searchMatchesCount = this.collection.where({ search_matched: true }).length; this.searchMatchesCount = this.collection.where({ search_matched: true }).length;
}, },
// Send a message to the aria-live region to announce how many search results. /**
* Sends a message to the aria-live region to announce how many search results.
*/
announceSearchMatches: _.debounce( function() { announceSearchMatches: _.debounce( function() {
var message = l10n.widgetsFound.replace( '%d', this.searchMatchesCount ) ; var message = l10n.widgetsFound.replace( '%d', this.searchMatchesCount ) ;
@ -258,7 +264,9 @@
wp.a11y.speak( message ); wp.a11y.speak( message );
}, 500 ), }, 500 ),
// Changes visibility of available widgets /**
* Changes visibility of available widgets.
*/
updateList: function() { updateList: function() {
this.collection.each( function( widget ) { this.collection.each( function( widget ) {
var widgetTpl = $( '#widget-tpl-' + widget.id ); var widgetTpl = $( '#widget-tpl-' + widget.id );
@ -269,19 +277,25 @@
} ); } );
}, },
// Highlights a widget /**
* Highlights a widget.
*/
select: function( widgetTpl ) { select: function( widgetTpl ) {
this.selected = $( widgetTpl ); this.selected = $( widgetTpl );
this.selected.siblings( '.widget-tpl' ).removeClass( 'selected' ); this.selected.siblings( '.widget-tpl' ).removeClass( 'selected' );
this.selected.addClass( 'selected' ); this.selected.addClass( 'selected' );
}, },
// Highlights a widget on focus /**
* Highlights a widget on focus.
*/
focus: function( event ) { focus: function( event ) {
this.select( $( event.currentTarget ) ); this.select( $( event.currentTarget ) );
}, },
// Submit handler for keypress and click on widget /**
* Handles submit for keypress and click on widget.
*/
_submit: function( event ) { _submit: function( event ) {
// Only proceed with keypress if it is Enter or Spacebar // Only proceed with keypress if it is Enter or Spacebar
if ( event.type === 'keypress' && ( event.which !== 13 && event.which !== 32 ) ) { if ( event.type === 'keypress' && ( event.which !== 13 && event.which !== 32 ) ) {
@ -291,7 +305,9 @@
this.submit( $( event.currentTarget ) ); this.submit( $( event.currentTarget ) );
}, },
// Adds a selected widget to the sidebar /**
* Adds a selected widget to the sidebar.
*/
submit: function( widgetTpl ) { submit: function( widgetTpl ) {
var widgetId, widget, widgetFormControl; var widgetId, widget, widgetFormControl;
@ -319,7 +335,9 @@
this.close(); this.close();
}, },
// Opens the panel /**
* Opens the panel.
*/
open: function( sidebarControl ) { open: function( sidebarControl ) {
this.currentSidebarControl = sidebarControl; this.currentSidebarControl = sidebarControl;
@ -346,7 +364,9 @@
} }
}, },
// Closes the panel /**
* Closes the panel.
*/
close: function( options ) { close: function( options ) {
options = options || {}; options = options || {};
@ -362,7 +382,9 @@
this.$search.val( '' ); this.$search.val( '' );
}, },
// Add keyboard accessiblity to the panel /**
* Adds keyboard accessiblity to the panel.
*/
keyboardAccessible: function( event ) { keyboardAccessible: function( event ) {
var isEnter = ( event.which === 13 ), var isEnter = ( event.which === 13 ),
isEsc = ( event.which === 27 ), isEsc = ( event.which === 27 ),
@ -424,6 +446,8 @@
* Handlers for the widget-synced event, organized by widget ID base. * Handlers for the widget-synced event, organized by widget ID base.
* Other widgets may provide their own update handlers by adding * Other widgets may provide their own update handlers by adding
* listeners for the widget-synced event. * listeners for the widget-synced event.
*
* @alias wp.customize.Widgets.formSyncHandlers
*/ */
api.Widgets.formSyncHandlers = { api.Widgets.formSyncHandlers = {
@ -446,23 +470,22 @@
} }
}; };
/** api.Widgets.WidgetControl = api.Control.extend(/** @lends wp.customize.Widgets.WidgetControl.prototype */{
* wp.customize.Widgets.WidgetControl
*
* Customizer control for widgets.
* Note that 'widget_form' must match the WP_Widget_Form_Customize_Control::$type
*
* @constructor
* @augments wp.customize.Control
*/
api.Widgets.WidgetControl = api.Control.extend({
defaultExpandedArguments: { defaultExpandedArguments: {
duration: 'fast', duration: 'fast',
completeCallback: $.noop completeCallback: $.noop
}, },
/** /**
* wp.customize.Widgets.WidgetControl
*
* Customizer control for widgets.
* Note that 'widget_form' must match the WP_Widget_Form_Customize_Control::$type
*
* @since 4.1.0 * @since 4.1.0
*
* @constructs wp.customize.Widgets.WidgetControl
* @augments wp.customize.Control
*/ */
initialize: function( id, options ) { initialize: function( id, options ) {
var control = this; var control = this;
@ -943,7 +966,7 @@
* *
* @param {Boolean} active * @param {Boolean} active
* @param {Object} args * @param {Object} args
* @param {Callback} args.completeCallback * @param {function} args.completeCallback
*/ */
onChangeActive: function ( active, args ) { onChangeActive: function ( active, args ) {
// Note: there is a second 'args' parameter being passed, merged on top of this.defaultActiveArguments // Note: there is a second 'args' parameter being passed, merged on top of this.defaultActiveArguments
@ -1574,8 +1597,11 @@
* Customizer panel containing the widget area sections. * Customizer panel containing the widget area sections.
* *
* @since 4.4.0 * @since 4.4.0
*
* @class wp.customize.Widgets.WidgetsPanel
* @augments wp.customize.Panel
*/ */
api.Widgets.WidgetsPanel = api.Panel.extend({ api.Widgets.WidgetsPanel = api.Panel.extend(/** @lends wp.customize.Widgets.WigetsPanel.prototype */{
/** /**
* Add and manage the display of the no-rendered-areas notice. * Add and manage the display of the no-rendered-areas notice.
@ -1695,8 +1721,11 @@
* Customizer section representing a widget area widget * Customizer section representing a widget area widget
* *
* @since 4.1.0 * @since 4.1.0
*
* @class wp.customize.Widgets.SidebarSection
* @augments wp.customize.Section
*/ */
api.Widgets.SidebarSection = api.Section.extend({ api.Widgets.SidebarSection = api.Section.extend(/** @lends wp.customize.Widgets.SidebarSection.prototype */{
/** /**
* Sync the section's active state back to the Backbone model's is_rendered attribute * Sync the section's active state back to the Backbone model's is_rendered attribute
@ -1722,10 +1751,10 @@
* *
* @since 3.9.0 * @since 3.9.0
* *
* @constructor * @class wp.customize.Widgets.SidebarControl
* @augments wp.customize.Control * @augments wp.customize.Control
*/ */
api.Widgets.SidebarControl = api.Control.extend({ api.Widgets.SidebarControl = api.Control.extend(/** @lends wp.customize.Widgets.SidebarControl.prototype */{
/** /**
* Set up the control * Set up the control

3
src/wp-admin/js/editor.js
View File

@ -1236,8 +1236,9 @@ window.wp = window.wp || {};
} }
/** /**
* @namespace {SwitchEditors} switchEditors
* Expose the switch editors to be used globally. * Expose the switch editors to be used globally.
*
* @namespace switchEditors
*/ */
window.switchEditors = new SwitchEditors(); window.switchEditors = new SwitchEditors();

8
src/wp-admin/js/image-edit.js
View File

@ -614,6 +614,8 @@
/** /**
* @summary Sets the CSS styles and binds events for locking the aspect ratio. * @summary Sets the CSS styles and binds events for locking the aspect ratio.
* *
* @ignore
*
* @param {jQuery} img The preview image. * @param {jQuery} img The preview image.
*/ */
onInit: function( img ) { onInit: function( img ) {
@ -645,6 +647,8 @@
/** /**
* @summary Event triggered when starting a selection. * @summary Event triggered when starting a selection.
* *
* @ignore
*
* @returns {void} * @returns {void}
*/ */
onSelectStart: function() { onSelectStart: function() {
@ -653,6 +657,8 @@
/** /**
* @summary Event triggered when the selection is ended. * @summary Event triggered when the selection is ended.
* *
* @ignore
*
* @param {object} img jQuery object representing the image. * @param {object} img jQuery object representing the image.
* @param {object} c The selection. * @param {object} c The selection.
* *
@ -665,6 +671,8 @@
/** /**
* @summary Event triggered when the selection changes. * @summary Event triggered when the selection changes.
* *
* @ignore
*
* @param {object} img jQuery object representing the image. * @param {object} img jQuery object representing the image.
* @param {object} c The selection. * @param {object} c The selection.
* *

3
src/wp-admin/js/inline-edit-post.js
View File

@ -10,10 +10,9 @@ window.wp = window.wp || {};
/** /**
* Manages the quick edit and bulk edit windows for editing posts or pages. * Manages the quick edit and bulk edit windows for editing posts or pages.
* *
* @namespace * @namespace inlineEditPost
* *
* @since 2.7.0 * @since 2.7.0
* @access public
* *
* @type {Object} * @type {Object}
* *

3
src/wp-admin/js/media.js
View File

@ -5,8 +5,7 @@
* *
* @since 2.7.0 * @since 2.7.0
* *
* @global * @namespace findPosts
* @namespace
* *
* @requires jQuery * @requires jQuery
*/ */

7
src/wp-admin/js/nav-menu.js
View File

@ -10,6 +10,11 @@
/* global menus, postboxes, columns, isRtl, navMenuL10n, ajaxurl */ /* global menus, postboxes, columns, isRtl, navMenuL10n, ajaxurl */
/**
* Contains all the functions to handle WordPress navigation menus administration.
*
* @namespace
*/
var wpNavMenu; var wpNavMenu;
(function($) { (function($) {
@ -167,6 +172,8 @@ var wpNavMenu;
/** /**
* Adds selected menu items to the menu. * Adds selected menu items to the menu.
* *
* @ignore
*
* @param jQuery metabox The metabox jQuery object. * @param jQuery metabox The metabox jQuery object.
*/ */
addSelectedToMenu : function(processMethod) { addSelectedToMenu : function(processMethod) {

2
src/wp-admin/js/plugin-install.js
View File

@ -1,7 +1,7 @@
/* global plugininstallL10n, tb_click, tb_remove */ /* global plugininstallL10n, tb_click, tb_remove */
/** /**
* Functionality for the plugin install screens. * @file Functionality for the plugin install screens.
*/ */
var tb_position; var tb_position;
jQuery( document ).ready( function( $ ) { jQuery( document ).ready( function( $ ) {

14
src/wp-admin/js/post.js
View File

@ -4,7 +4,7 @@
/** /**
* Contains all dynamic functionality needed on post and term pages. * Contains all dynamic functionality needed on post and term pages.
* *
* @summary Control page and term functionality. * @file Control page and term functionality.
*/ */
var commentsBox, WPSetThumbnailHTML, WPSetThumbnailID, WPRemoveThumbnail, wptitlehint, makeSlugeditClickable, editPermalink; var commentsBox, WPSetThumbnailHTML, WPSetThumbnailID, WPRemoveThumbnail, wptitlehint, makeSlugeditClickable, editPermalink;
@ -31,11 +31,11 @@ window.wp = window.wp || {};
/** /**
* Fetch comments using AJAX and display them in the box. * Fetch comments using AJAX and display them in the box.
* *
* @memberof commentsBox
*
* @param {int} total Total number of comments for this post. * @param {int} total Total number of comments for this post.
* @param {int} num Optional. Number of comments to fetch, defaults to 20. * @param {int} num Optional. Number of comments to fetch, defaults to 20.
* @returns {boolean} Always returns false. * @returns {boolean} Always returns false.
*
* @memberof commentsBox
*/ */
get : function(total, num) { get : function(total, num) {
var st = this.st, data; var st = this.st, data;
@ -662,6 +662,8 @@ jQuery(document).ready( function($) {
/** /**
* Add current post_ID to request to fetch custom fields * Add current post_ID to request to fetch custom fields
* *
* @ignore
*
* @param {Object} s Request object. * @param {Object} s Request object.
* *
* @returns {Object} Data modified with post_ID attached. * @returns {Object} Data modified with post_ID attached.
@ -672,6 +674,8 @@ jQuery(document).ready( function($) {
}, },
/** /**
* Show the listing of custom fields after fetching. * Show the listing of custom fields after fetching.
*
* @ignore
*/ */
addAfter: function() { addAfter: function() {
$('table#list-table').show(); $('table#list-table').show();
@ -689,6 +693,8 @@ jQuery(document).ready( function($) {
/** /**
* When the visibility of a post changes sub-options should be shown or hidden. * When the visibility of a post changes sub-options should be shown or hidden.
* *
* @ignore
*
* @returns void * @returns void
*/ */
updateVisibility = function() { updateVisibility = function() {
@ -711,6 +717,8 @@ jQuery(document).ready( function($) {
/** /**
* Make sure all labels represent the current settings. * Make sure all labels represent the current settings.
* *
* @ignore
*
* @returns {boolean} False when an invalid timestamp has been selected, otherwise True. * @returns {boolean} False when an invalid timestamp has been selected, otherwise True.
*/ */
updateText = function() { updateText = function() {

6
src/wp-admin/js/postbox.js
View File

@ -81,6 +81,8 @@ var postboxes;
* Contains a jQuery object with the relevant postbox element. * Contains a jQuery object with the relevant postbox element.
* *
* @since 4.0.0 * @since 4.0.0
* @ignore
*
* @event postboxes#postbox-toggled * @event postboxes#postbox-toggled
* @type {Object} * @type {Object}
*/ */
@ -137,6 +139,8 @@ var postboxes;
* clicked this function will hide or show the relevant postboxes. * clicked this function will hide or show the relevant postboxes.
* *
* @since 2.7.0 * @since 2.7.0
* @ignore
*
* @fires postboxes#postbox-toggled * @fires postboxes#postbox-toggled
* *
* @returns {void} * @returns {void}
@ -383,6 +387,8 @@ var postboxes;
* Fires when the amount of columns on the post edit page has been changed. * Fires when the amount of columns on the post edit page has been changed.
* *
* @since 4.0.0 * @since 4.0.0
* @ignore
*
* @event postboxes#postboxes-columnchange * @event postboxes#postboxes-columnchange
*/ */
$( document ).trigger( 'postboxes-columnchange' ); $( document ).trigger( 'postboxes-columnchange' );

52
src/wp-admin/js/updates.js
View File

@ -2,9 +2,6 @@
* Functions for ajaxified updates, deletions and installs inside the WordPress admin. * Functions for ajaxified updates, deletions and installs inside the WordPress admin.
* *
* @version 4.2.0 * @version 4.2.0
*
* @package WordPress
* @subpackage Administration
*/ */
/* global pagenow */ /* global pagenow */
@ -38,7 +35,7 @@
* *
* @since 4.2.0 * @since 4.2.0
* *
* @type {object} * @namespace wp.updates
*/ */
wp.updates = {}; wp.updates = {};
@ -84,18 +81,18 @@
* @since 4.2.0 * @since 4.2.0
* @since 4.6.0 Added `available` property to indicate whether credentials have been provided. * @since 4.6.0 Added `available` property to indicate whether credentials have been provided.
* *
* @type {object} filesystemCredentials Holds filesystem credentials. * @type {Object}
* @type {object} filesystemCredentials.ftp Holds FTP credentials. * @property {Object} filesystemCredentials.ftp Holds FTP credentials.
* @type {string} filesystemCredentials.ftp.host FTP host. Default empty string. * @property {string} filesystemCredentials.ftp.host FTP host. Default empty string.
* @type {string} filesystemCredentials.ftp.username FTP user name. Default empty string. * @property {string} filesystemCredentials.ftp.username FTP user name. Default empty string.
* @type {string} filesystemCredentials.ftp.password FTP password. Default empty string. * @property {string} filesystemCredentials.ftp.password FTP password. Default empty string.
* @type {string} filesystemCredentials.ftp.connectionType Type of FTP connection. 'ssh', 'ftp', or 'ftps'. * @property {string} filesystemCredentials.ftp.connectionType Type of FTP connection. 'ssh', 'ftp', or 'ftps'.
* Default empty string. * Default empty string.
* @type {object} filesystemCredentials.ssh Holds SSH credentials. * @property {Object} filesystemCredentials.ssh Holds SSH credentials.
* @type {string} filesystemCredentials.ssh.publicKey The public key. Default empty string. * @property {string} filesystemCredentials.ssh.publicKey The public key. Default empty string.
* @type {string} filesystemCredentials.ssh.privateKey The private key. Default empty string. * @property {string} filesystemCredentials.ssh.privateKey The private key. Default empty string.
* @type {string} filesystemCredentials.fsNonce Filesystem credentials form nonce. * @property {string} filesystemCredentials.fsNonce Filesystem credentials form nonce.
* @type {bool} filesystemCredentials.available Whether filesystem credentials have been provided. * @property {bool} filesystemCredentials.available Whether filesystem credentials have been provided.
* Default 'false'. * Default 'false'.
*/ */
wp.updates.filesystemCredentials = { wp.updates.filesystemCredentials = {
@ -128,7 +125,7 @@
* *
* @since 4.6.0 * @since 4.6.0
* *
* @type {function} A function that lazily-compiles the template requested. * @type {function}
*/ */
wp.updates.adminNotice = wp.template( 'wp-updates-admin-notice' ); wp.updates.adminNotice = wp.template( 'wp-updates-admin-notice' );
@ -407,7 +404,6 @@
* @since 4.2.0 * @since 4.2.0
* @since 4.6.0 More accurately named `updatePluginSuccess`. * @since 4.6.0 More accurately named `updatePluginSuccess`.
* *
* @typedef {object} updatePluginSuccess
* @param {object} response Response from the server. * @param {object} response Response from the server.
* @param {string} response.slug Slug of the plugin to be updated. * @param {string} response.slug Slug of the plugin to be updated.
* @param {string} response.plugin Basename of the plugin to be updated. * @param {string} response.plugin Basename of the plugin to be updated.
@ -452,7 +448,6 @@
* @since 4.2.0 * @since 4.2.0
* @since 4.6.0 More accurately named `updatePluginError`. * @since 4.6.0 More accurately named `updatePluginError`.
* *
* @typedef {object} updatePluginError
* @param {object} response Response from the server. * @param {object} response Response from the server.
* @param {string} response.slug Slug of the plugin to be updated. * @param {string} response.slug Slug of the plugin to be updated.
* @param {string} response.plugin Basename of the plugin to be updated. * @param {string} response.plugin Basename of the plugin to be updated.
@ -574,7 +569,6 @@
* *
* @since 4.6.0 * @since 4.6.0
* *
* @typedef {object} installPluginSuccess
* @param {object} response Response from the server. * @param {object} response Response from the server.
* @param {string} response.slug Slug of the installed plugin. * @param {string} response.slug Slug of the installed plugin.
* @param {string} response.pluginName Name of the installed plugin. * @param {string} response.pluginName Name of the installed plugin.
@ -610,7 +604,6 @@
* *
* @since 4.6.0 * @since 4.6.0
* *
* @typedef {object} installPluginError
* @param {object} response Response from the server. * @param {object} response Response from the server.
* @param {string} response.slug Slug of the plugin to be installed. * @param {string} response.slug Slug of the plugin to be installed.
* @param {string=} response.pluginName Optional. Name of the plugin to be installed. * @param {string=} response.pluginName Optional. Name of the plugin to be installed.
@ -661,7 +654,6 @@
* *
* @since 4.6.0 * @since 4.6.0
* *
* @typedef {object} installImporterSuccess
* @param {object} response Response from the server. * @param {object} response Response from the server.
* @param {string} response.slug Slug of the installed plugin. * @param {string} response.slug Slug of the installed plugin.
* @param {string} response.pluginName Name of the installed plugin. * @param {string} response.pluginName Name of the installed plugin.
@ -693,7 +685,6 @@
* *
* @since 4.6.0 * @since 4.6.0
* *
* @typedef {object} installImporterError
* @param {object} response Response from the server. * @param {object} response Response from the server.
* @param {string} response.slug Slug of the plugin to be installed. * @param {string} response.slug Slug of the plugin to be installed.
* @param {string=} response.pluginName Optional. Name of the plugin to be installed. * @param {string=} response.pluginName Optional. Name of the plugin to be installed.
@ -768,8 +759,7 @@
* *
* @since 4.6.0 * @since 4.6.0
* *
* @typedef {object} deletePluginSuccess * @param {Object} response Response from the server.
* @param {object} response Response from the server.
* @param {string} response.slug Slug of the plugin that was deleted. * @param {string} response.slug Slug of the plugin that was deleted.
* @param {string} response.plugin Base name of the plugin that was deleted. * @param {string} response.plugin Base name of the plugin that was deleted.
* @param {string} response.pluginName Name of the plugin that was deleted. * @param {string} response.pluginName Name of the plugin that was deleted.
@ -783,7 +773,11 @@
$pluginRow = $( this ), $pluginRow = $( this ),
columnCount = $form.find( 'thead th:not(.hidden), thead td' ).length, columnCount = $form.find( 'thead th:not(.hidden), thead td' ).length,
pluginDeletedRow = wp.template( 'item-deleted-row' ), pluginDeletedRow = wp.template( 'item-deleted-row' ),
/** @type {object} plugins Base names of plugins in their different states. */ /**
* Plugins Base names of plugins in their different states.
*
* @type {Object}
*/
plugins = settings.plugins; plugins = settings.plugins;
// Add a success message after deleting a plugin. // Add a success message after deleting a plugin.
@ -858,7 +852,6 @@
* *
* @since 4.6.0 * @since 4.6.0
* *
* @typedef {object} deletePluginError
* @param {object} response Response from the server. * @param {object} response Response from the server.
* @param {string} response.slug Slug of the plugin to be deleted. * @param {string} response.slug Slug of the plugin to be deleted.
* @param {string} response.plugin Base name of the plugin to be deleted * @param {string} response.plugin Base name of the plugin to be deleted
@ -971,7 +964,6 @@
* *
* @since 4.6.0 * @since 4.6.0
* *
* @typedef {object} updateThemeSuccess
* @param {object} response * @param {object} response
* @param {string} response.slug Slug of the theme to be updated. * @param {string} response.slug Slug of the theme to be updated.
* @param {object} response.theme Updated theme. * @param {object} response.theme Updated theme.
@ -1033,7 +1025,6 @@
* *
* @since 4.6.0 * @since 4.6.0
* *
* @typedef {object} updateThemeError
* @param {object} response Response from the server. * @param {object} response Response from the server.
* @param {string} response.slug Slug of the theme to be updated. * @param {string} response.slug Slug of the theme to be updated.
* @param {string} response.errorCode Error code for the error that occurred. * @param {string} response.errorCode Error code for the error that occurred.
@ -1119,7 +1110,6 @@
* *
* @since 4.6.0 * @since 4.6.0
* *
* @typedef {object} installThemeSuccess
* @param {object} response Response from the server. * @param {object} response Response from the server.
* @param {string} response.slug Slug of the theme to be installed. * @param {string} response.slug Slug of the theme to be installed.
* @param {string} response.customizeUrl URL to the Customizer for the just installed theme. * @param {string} response.customizeUrl URL to the Customizer for the just installed theme.
@ -1170,7 +1160,6 @@
* *
* @since 4.6.0 * @since 4.6.0
* *
* @typedef {object} installThemeError
* @param {object} response Response from the server. * @param {object} response Response from the server.
* @param {string} response.slug Slug of the theme to be installed. * @param {string} response.slug Slug of the theme to be installed.
* @param {string} response.errorCode Error code for the error that occurred. * @param {string} response.errorCode Error code for the error that occurred.
@ -1268,7 +1257,6 @@
* *
* @since 4.6.0 * @since 4.6.0
* *
* @typedef {object} deleteThemeSuccess
* @param {object} response Response from the server. * @param {object} response Response from the server.
* @param {string} response.slug Slug of the theme that was deleted. * @param {string} response.slug Slug of the theme that was deleted.
*/ */
@ -1327,7 +1315,6 @@
* *
* @since 4.6.0 * @since 4.6.0
* *
* @typedef {object} deleteThemeError
* @param {object} response Response from the server. * @param {object} response Response from the server.
* @param {string} response.slug Slug of the theme to be deleted. * @param {string} response.slug Slug of the theme to be deleted.
* @param {string} response.errorCode Error code for the error that occurred. * @param {string} response.errorCode Error code for the error that occurred.
@ -1601,7 +1588,6 @@
* *
* @since 4.6.0 * @since 4.6.0
* *
* @typedef {object} maybeHandleCredentialError
* @param {object} response Response from the server. * @param {object} response Response from the server.
* @param {string} response.errorCode Error code for the error that occurred. * @param {string} response.errorCode Error code for the error that occurred.
* @param {string} response.errorMessage The error that occurred. * @param {string} response.errorMessage The error that occurred.

4
src/wp-admin/js/widgets.js
View File

@ -245,6 +245,8 @@ wpWidgets = {
/** /**
* Open Sidebar when a Widget gets dragged over it. * Open Sidebar when a Widget gets dragged over it.
* *
* @ignore
*
* @param {object} event jQuery event object. * @param {object} event jQuery event object.
*/ */
over: function( event ) { over: function( event ) {
@ -268,6 +270,8 @@ wpWidgets = {
/** /**
* Close Sidebar when the Widget gets dragged out of it. * Close Sidebar when the Widget gets dragged out of it.
* *
* @ignore
*
* @param {object} event jQuery event object. * @param {object} event jQuery event object.
*/ */
out: function( event ) { out: function( event ) {

41
src/wp-admin/js/widgets/custom-html-widgets.js
View File

@ -1,6 +1,11 @@
/* global wp */ /* global wp */
/* eslint consistent-this: [ "error", "control" ] */ /* eslint consistent-this: [ "error", "control" ] */
/* eslint no-magic-numbers: ["error", { "ignore": [0,1,-1] }] */ /* eslint no-magic-numbers: ["error", { "ignore": [0,1,-1] }] */
/**
* @namespace wp.customHtmlWidget
* @memberOf wp
*/
wp.customHtmlWidgets = ( function( $ ) { wp.customHtmlWidgets = ( function( $ ) {
'use strict'; 'use strict';
@ -15,14 +20,7 @@ wp.customHtmlWidgets = ( function( $ ) {
} }
}; };
/** component.CustomHtmlWidgetControl = Backbone.View.extend(/** @lends wp.customHtmlWidgets.CustomHtmlWidgetControl.prototype */{
* Text widget control.
*
* @class CustomHtmlWidgetControl
* @constructor
* @abstract
*/
component.CustomHtmlWidgetControl = Backbone.View.extend({
/** /**
* View events. * View events.
@ -32,11 +30,16 @@ wp.customHtmlWidgets = ( function( $ ) {
events: {}, events: {},
/** /**
* Initialize. * Text widget control.
*
* @constructs wp.customHtmlWidgets.CustomHtmlWidgetControl
* @augments Backbone.View
* @abstract
* *
* @param {Object} options - Options. * @param {Object} options - Options.
* @param {jQuery} options.el - Control field container element. * @param {jQuery} options.el - Control field container element.
* @param {jQuery} options.syncContainer - Container element where fields are synced for the server. * @param {jQuery} options.syncContainer - Container element where fields are synced for the server.
*
* @returns {void} * @returns {void}
*/ */
initialize: function initialize( options ) { initialize: function initialize( options ) {
@ -171,6 +174,8 @@ wp.customHtmlWidgets = ( function( $ ) {
/** /**
* Handle tabbing to the field before the editor. * Handle tabbing to the field before the editor.
* *
* @ignore
*
* @returns {void} * @returns {void}
*/ */
onTabPrevious: function onTabPrevious() { onTabPrevious: function onTabPrevious() {
@ -180,6 +185,8 @@ wp.customHtmlWidgets = ( function( $ ) {
/** /**
* Handle tabbing to the field after the editor. * Handle tabbing to the field after the editor.
* *
* @ignore
*
* @returns {void} * @returns {void}
*/ */
onTabNext: function onTabNext() { onTabNext: function onTabNext() {
@ -190,6 +197,8 @@ wp.customHtmlWidgets = ( function( $ ) {
/** /**
* Disable save button and store linting errors for use in updateFields. * Disable save button and store linting errors for use in updateFields.
* *
* @ignore
*
* @param {Array} errorAnnotations - Error notifications. * @param {Array} errorAnnotations - Error notifications.
* @returns {void} * @returns {void}
*/ */
@ -200,6 +209,8 @@ wp.customHtmlWidgets = ( function( $ ) {
/** /**
* Update error notice. * Update error notice.
* *
* @ignore
*
* @param {Array} errorAnnotations - Error annotations. * @param {Array} errorAnnotations - Error annotations.
* @returns {void} * @returns {void}
*/ */
@ -259,6 +270,8 @@ wp.customHtmlWidgets = ( function( $ ) {
/** /**
* Mapping of widget ID to instances of CustomHtmlWidgetControl subclasses. * Mapping of widget ID to instances of CustomHtmlWidgetControl subclasses.
* *
* @alias wp.customHtmlWidgets.widgetControls
*
* @type {Object.<string, wp.textWidgets.CustomHtmlWidgetControl>} * @type {Object.<string, wp.textWidgets.CustomHtmlWidgetControl>}
*/ */
component.widgetControls = {}; component.widgetControls = {};
@ -266,8 +279,11 @@ wp.customHtmlWidgets = ( function( $ ) {
/** /**
* Handle widget being added or initialized for the first time at the widget-added event. * Handle widget being added or initialized for the first time at the widget-added event.
* *
* @alias wp.customHtmlWidgets.handleWidgetAdded
*
* @param {jQuery.Event} event - Event. * @param {jQuery.Event} event - Event.
* @param {jQuery} widgetContainer - Widget container element. * @param {jQuery} widgetContainer - Widget container element.
*
* @returns {void} * @returns {void}
*/ */
component.handleWidgetAdded = function handleWidgetAdded( event, widgetContainer ) { component.handleWidgetAdded = function handleWidgetAdded( event, widgetContainer ) {
@ -325,6 +341,8 @@ wp.customHtmlWidgets = ( function( $ ) {
/** /**
* Setup widget in accessibility mode. * Setup widget in accessibility mode.
* *
* @alias wp.customHtmlWidgets.setupAccessibleMode
*
* @returns {void} * @returns {void}
*/ */
component.setupAccessibleMode = function setupAccessibleMode() { component.setupAccessibleMode = function setupAccessibleMode() {
@ -358,6 +376,8 @@ wp.customHtmlWidgets = ( function( $ ) {
* the widgets admin screen and also via the 'widget-synced' event when making * the widgets admin screen and also via the 'widget-synced' event when making
* a change to a widget in the customizer. * a change to a widget in the customizer.
* *
* @alias wp.customHtmlWidgets.handleWidgetUpdated
*
* @param {jQuery.Event} event - Event. * @param {jQuery.Event} event - Event.
* @param {jQuery} widgetContainer - Widget container element. * @param {jQuery} widgetContainer - Widget container element.
* @returns {void} * @returns {void}
@ -387,7 +407,10 @@ wp.customHtmlWidgets = ( function( $ ) {
* When WordPress enqueues this script, it should have an inline script * When WordPress enqueues this script, it should have an inline script
* attached which calls wp.textWidgets.init(). * attached which calls wp.textWidgets.init().
* *
* @alias wp.customHtmlWidgets.init
*
* @param {object} settings - Options for code editor, exported from PHP. * @param {object} settings - Options for code editor, exported from PHP.
*
* @returns {void} * @returns {void}
*/ */
component.init = function init( settings ) { component.init = function init( settings ) {

16
src/wp-admin/js/widgets/media-audio-widget.js
View File

@ -7,10 +7,10 @@
/** /**
* Custom audio details frame that removes the replace-audio state. * Custom audio details frame that removes the replace-audio state.
* *
* @class AudioDetailsMediaFrame * @class wp.mediaWidgets.controlConstructors~AudioDetailsMediaFrame
* @constructor * @augments wp.media.view.MediaFrame.AudioDetails
*/ */
AudioDetailsMediaFrame = wp.media.view.MediaFrame.AudioDetails.extend({ AudioDetailsMediaFrame = wp.media.view.MediaFrame.AudioDetails.extend(/** @lends wp.mediaWidgets.controlConstructors~AudioDetailsMediaFrame.prototype */{
/** /**
* Create the default states. * Create the default states.
@ -40,8 +40,8 @@
* *
* See WP_Widget_Audio::enqueue_admin_scripts() for amending prototype from PHP exports. * See WP_Widget_Audio::enqueue_admin_scripts() for amending prototype from PHP exports.
* *
* @class AudioWidgetModel * @class wp.mediaWidgets.modelConstructors.media_audio
* @constructor * @augments wp.mediaWidgets.MediaWidgetModel
*/ */
AudioWidgetModel = component.MediaWidgetModel.extend({}); AudioWidgetModel = component.MediaWidgetModel.extend({});
@ -50,10 +50,10 @@
* *
* See WP_Widget_Audio::enqueue_admin_scripts() for amending prototype from PHP exports. * See WP_Widget_Audio::enqueue_admin_scripts() for amending prototype from PHP exports.
* *
* @class AudioWidgetModel * @class wp.mediaWidgets.controlConstructors.media_audio
* @constructor * @augments wp.mediaWidgets.MediaWidgetControl
*/ */
AudioWidgetControl = component.MediaWidgetControl.extend({ AudioWidgetControl = component.MediaWidgetControl.extend(/** @lends wp.mediaWidgets.controlConstructors.media_audio.prototype */{
/** /**
* Show display settings. * Show display settings.

31
src/wp-admin/js/widgets/media-gallery-widget.js
View File

@ -8,10 +8,10 @@
* Custom gallery details frame. * Custom gallery details frame.
* *
* @since 4.9.0 * @since 4.9.0
* @class GalleryDetailsMediaFrame * @class wp.mediaWidgets~GalleryDetailsMediaFrame
* @constructor * @augments wp.media.view.MediaFrame.Post
*/ */
GalleryDetailsMediaFrame = wp.media.view.MediaFrame.Post.extend( { GalleryDetailsMediaFrame = wp.media.view.MediaFrame.Post.extend(/** @lends wp.mediaWidgets~GalleryDetailsMediaFrame.prototype */{
/** /**
* Create the default states. * Create the default states.
@ -53,21 +53,13 @@
* See WP_Widget_Gallery::enqueue_admin_scripts() for amending prototype from PHP exports. * See WP_Widget_Gallery::enqueue_admin_scripts() for amending prototype from PHP exports.
* *
* @since 4.9.0 * @since 4.9.0
* @class GalleryWidgetModel *
* @constructor * @class wp.mediaWidgets.modelConstructors.media_gallery
* @augments wp.mediaWidgets.MediaWidgetModel
*/ */
GalleryWidgetModel = component.MediaWidgetModel.extend( {} ); GalleryWidgetModel = component.MediaWidgetModel.extend(/** @lends wp.mediaWidgets.modelConstructors.media_gallery.prototype */{} );
/** GalleryWidgetControl = component.MediaWidgetControl.extend(/** @lends wp.mediaWidgets.controlConstructors.media_gallery.prototype */{
* Gallery widget control.
*
* See WP_Widget_Gallery::enqueue_admin_scripts() for amending prototype from PHP exports.
*
* @since 4.9.0
* @class GalleryWidgetControl
* @constructor
*/
GalleryWidgetControl = component.MediaWidgetControl.extend( {
/** /**
* View events. * View events.
@ -80,7 +72,12 @@
} ), } ),
/** /**
* Initialize. * Gallery widget control.
*
* See WP_Widget_Gallery::enqueue_admin_scripts() for amending prototype from PHP exports.
*
* @constructs wp.mediaWidgets.controlConstructors.media_gallery
* @augments wp.mediaWidgets.MediaWidgetControl
* *
* @since 4.9.0 * @since 4.9.0
* @param {Object} options - Options. * @param {Object} options - Options.

10
src/wp-admin/js/widgets/media-image-widget.js
View File

@ -9,8 +9,8 @@
* *
* See WP_Widget_Media_Image::enqueue_admin_scripts() for amending prototype from PHP exports. * See WP_Widget_Media_Image::enqueue_admin_scripts() for amending prototype from PHP exports.
* *
* @class ImageWidgetModel * @class wp.mediaWidgets.modelConstructors.media_image
* @constructor * @augments wp.mediaWidgets.MediaWidgetModel
*/ */
ImageWidgetModel = component.MediaWidgetModel.extend({}); ImageWidgetModel = component.MediaWidgetModel.extend({});
@ -19,10 +19,10 @@
* *
* See WP_Widget_Media_Image::enqueue_admin_scripts() for amending prototype from PHP exports. * See WP_Widget_Media_Image::enqueue_admin_scripts() for amending prototype from PHP exports.
* *
* @class ImageWidgetModel * @class wp.mediaWidgets.controlConstructors.media_audio
* @constructor * @augments wp.mediaWidgets.MediaWidgetControl
*/ */
ImageWidgetControl = component.MediaWidgetControl.extend({ ImageWidgetControl = component.MediaWidgetControl.extend(/** @lends wp.mediaWidgets.controlConstructors.media_image.prototype */{
/** /**
* View events. * View events.

18
src/wp-admin/js/widgets/media-video-widget.js
View File

@ -7,10 +7,12 @@
/** /**
* Custom video details frame that removes the replace-video state. * Custom video details frame that removes the replace-video state.
* *
* @class VideoDetailsMediaFrame * @class wp.mediaWidgets.controlConstructors~VideoDetailsMediaFrame
* @constructor * @augments wp.media.view.MediaFrame.VideoDetails
*
* @private
*/ */
VideoDetailsMediaFrame = wp.media.view.MediaFrame.VideoDetails.extend({ VideoDetailsMediaFrame = wp.media.view.MediaFrame.VideoDetails.extend(/** @lends wp.mediaWidgets.controlConstructors~VideoDetailsMediaFrame.prototype */{
/** /**
* Create the default states. * Create the default states.
@ -49,8 +51,8 @@
* *
* See WP_Widget_Video::enqueue_admin_scripts() for amending prototype from PHP exports. * See WP_Widget_Video::enqueue_admin_scripts() for amending prototype from PHP exports.
* *
* @class VideoWidgetModel * @class wp.mediaWidgets.modelConstructors.media_video
* @constructor * @augments wp.mediaWidgets.MediaWidgetModel
*/ */
VideoWidgetModel = component.MediaWidgetModel.extend({}); VideoWidgetModel = component.MediaWidgetModel.extend({});
@ -59,10 +61,10 @@
* *
* See WP_Widget_Video::enqueue_admin_scripts() for amending prototype from PHP exports. * See WP_Widget_Video::enqueue_admin_scripts() for amending prototype from PHP exports.
* *
* @class VideoWidgetControl * @class wp.mediaWidgets.controlConstructors.media_video
* @constructor * @augments wp.mediaWidgets.MediaWidgetControl
*/ */
VideoWidgetControl = component.MediaWidgetControl.extend({ VideoWidgetControl = component.MediaWidgetControl.extend(/** @lends wp.mediaWidgets.controlConstructors.media_video.prototype */{
/** /**
* Show display settings. * Show display settings.

78
src/wp-admin/js/widgets/media-widgets.js
View File

@ -1,4 +1,9 @@
/* eslint consistent-this: [ "error", "control" ] */ /* eslint consistent-this: [ "error", "control" ] */
/**
* @namespace wp.mediaWidgets
* @memberOf wp
*/
wp.mediaWidgets = ( function( $ ) { wp.mediaWidgets = ( function( $ ) {
'use strict'; 'use strict';
@ -9,6 +14,8 @@ wp.mediaWidgets = ( function( $ ) {
* *
* Media widgets register themselves by assigning subclasses of MediaWidgetControl onto this object by widget ID base. * Media widgets register themselves by assigning subclasses of MediaWidgetControl onto this object by widget ID base.
* *
* @memberOf wp.mediaWidgets
*
* @type {Object.<string, wp.mediaWidgets.MediaWidgetModel>} * @type {Object.<string, wp.mediaWidgets.MediaWidgetModel>}
*/ */
component.controlConstructors = {}; component.controlConstructors = {};
@ -18,22 +25,22 @@ wp.mediaWidgets = ( function( $ ) {
* *
* Media widgets register themselves by assigning subclasses of MediaWidgetControl onto this object by widget ID base. * Media widgets register themselves by assigning subclasses of MediaWidgetControl onto this object by widget ID base.
* *
* @memberOf wp.mediaWidgets
*
* @type {Object.<string, wp.mediaWidgets.MediaWidgetModel>} * @type {Object.<string, wp.mediaWidgets.MediaWidgetModel>}
*/ */
component.modelConstructors = {}; component.modelConstructors = {};
component.PersistentDisplaySettingsLibrary = wp.media.controller.Library.extend(/** @lends wp.mediaWidgets.PersistentDisplaySettingsLibrary.prototype */{
/** /**
* Library which persists the customized display settings across selections. * Library which persists the customized display settings across selections.
* *
* @class PersistentDisplaySettingsLibrary * @constructs wp.mediaWidgets.PersistentDisplaySettingsLibrary
* @constructor * @augments wp.media.controller.Library
*/
component.PersistentDisplaySettingsLibrary = wp.media.controller.Library.extend({
/**
* Initialize.
* *
* @param {Object} options - Options. * @param {Object} options - Options.
*
* @returns {void} * @returns {void}
*/ */
initialize: function initialize( options ) { initialize: function initialize( options ) {
@ -79,10 +86,10 @@ wp.mediaWidgets = ( function( $ ) {
/** /**
* Extended view for managing the embed UI. * Extended view for managing the embed UI.
* *
* @class MediaEmbedView * @class wp.mediaWidgets.MediaEmbedView
* @constructor * @augments wp.media.view.Embed
*/ */
component.MediaEmbedView = wp.media.view.Embed.extend({ component.MediaEmbedView = wp.media.view.Embed.extend(/** @lends wp.mediaWidgets.MediaEmbedView.prototype */{
/** /**
* Initialize. * Initialize.
@ -109,6 +116,9 @@ wp.mediaWidgets = ( function( $ ) {
* @returns {void} * @returns {void}
*/ */
refresh: function refresh() { refresh: function refresh() {
/**
* @class wp.mediaWidgets~Constructor
*/
var Constructor; var Constructor;
if ( 'image' === this.controller.options.mimeType ) { if ( 'image' === this.controller.options.mimeType ) {
@ -116,7 +126,7 @@ wp.mediaWidgets = ( function( $ ) {
} else { } else {
// This should be eliminated once #40450 lands of when this is merged into core. // This should be eliminated once #40450 lands of when this is merged into core.
Constructor = wp.media.view.EmbedLink.extend({ Constructor = wp.media.view.EmbedLink.extend(/** @lends wp.mediaWidgets~Constructor.prototype */{
/** /**
* Set the disabled state on the Add to Widget button. * Set the disabled state on the Add to Widget button.
@ -284,10 +294,10 @@ wp.mediaWidgets = ( function( $ ) {
/** /**
* Custom media frame for selecting uploaded media or providing media by URL. * Custom media frame for selecting uploaded media or providing media by URL.
* *
* @class MediaFrameSelect * @class wp.mediaWidgets.MediaFrameSelect
* @constructor * @augments wp.media.view.MediaFrame.Post
*/ */
component.MediaFrameSelect = wp.media.view.MediaFrame.Post.extend({ component.MediaFrameSelect = wp.media.view.MediaFrame.Post.extend(/** @lends wp.mediaWidgets.MediaFrameSelect.prototype */{
/** /**
* Create the default states. * Create the default states.
@ -357,6 +367,8 @@ wp.mediaWidgets = ( function( $ ) {
/** /**
* Handle click. * Handle click.
* *
* @ignore
*
* @fires wp.media.controller.State#insert() * @fires wp.media.controller.State#insert()
* @returns {void} * @returns {void}
*/ */
@ -408,14 +420,7 @@ wp.mediaWidgets = ( function( $ ) {
} }
}); });
/** component.MediaWidgetControl = Backbone.View.extend(/** @lends wp.mediaWidgets.MediaWidgetControl.prototype */{
* Media widget control.
*
* @class MediaWidgetControl
* @constructor
* @abstract
*/
component.MediaWidgetControl = Backbone.View.extend({
/** /**
* Translation strings. * Translation strings.
@ -473,12 +478,17 @@ wp.mediaWidgets = ( function( $ ) {
showDisplaySettings: true, showDisplaySettings: true,
/** /**
* Initialize. * Media Widget Control.
*
* @constructs wp.mediaWidgets.MediaWidgetControl
* @augments Backbone.View
* @abstract
* *
* @param {Object} options - Options. * @param {Object} options - Options.
* @param {Backbone.Model} options.model - Model. * @param {Backbone.Model} options.model - Model.
* @param {jQuery} options.el - Control field container element. * @param {jQuery} options.el - Control field container element.
* @param {jQuery} options.syncContainer - Container element where fields are synced for the server. * @param {jQuery} options.syncContainer - Container element where fields are synced for the server.
*
* @returns {void} * @returns {void}
*/ */
initialize: function initialize( options ) { initialize: function initialize( options ) {
@ -961,10 +971,10 @@ wp.mediaWidgets = ( function( $ ) {
/** /**
* Media widget model. * Media widget model.
* *
* @class MediaWidgetModel * @class wp.mediaWidgets.MediaWidgetModel
* @constructor * @augments Backbone.Model
*/ */
component.MediaWidgetModel = Backbone.Model.extend({ component.MediaWidgetModel = Backbone.Model.extend(/** @lends wp.mediaWidgets.MediaWidgetModel.prototype */{
/** /**
* Id attribute. * Id attribute.
@ -1085,15 +1095,19 @@ wp.mediaWidgets = ( function( $ ) {
/** /**
* Collection of all widget model instances. * Collection of all widget model instances.
* *
* @memberOf wp.mediaWidgets
*
* @type {Backbone.Collection} * @type {Backbone.Collection}
*/ */
component.modelCollection = new ( Backbone.Collection.extend({ component.modelCollection = new ( Backbone.Collection.extend( {
model: component.MediaWidgetModel model: component.MediaWidgetModel
}) )(); }) )();
/** /**
* Mapping of widget ID to instances of MediaWidgetControl subclasses. * Mapping of widget ID to instances of MediaWidgetControl subclasses.
* *
* @memberOf wp.mediaWidgets
*
* @type {Object.<string, wp.mediaWidgets.MediaWidgetControl>} * @type {Object.<string, wp.mediaWidgets.MediaWidgetControl>}
*/ */
component.widgetControls = {}; component.widgetControls = {};
@ -1101,8 +1115,11 @@ wp.mediaWidgets = ( function( $ ) {
/** /**
* Handle widget being added or initialized for the first time at the widget-added event. * Handle widget being added or initialized for the first time at the widget-added event.
* *
* @memberOf wp.mediaWidgets
*
* @param {jQuery.Event} event - Event. * @param {jQuery.Event} event - Event.
* @param {jQuery} widgetContainer - Widget container element. * @param {jQuery} widgetContainer - Widget container element.
*
* @returns {void} * @returns {void}
*/ */
component.handleWidgetAdded = function handleWidgetAdded( event, widgetContainer ) { component.handleWidgetAdded = function handleWidgetAdded( event, widgetContainer ) {
@ -1184,6 +1201,8 @@ wp.mediaWidgets = ( function( $ ) {
/** /**
* Setup widget in accessibility mode. * Setup widget in accessibility mode.
* *
* @memberOf wp.mediaWidgets
*
* @returns {void} * @returns {void}
*/ */
component.setupAccessibleMode = function setupAccessibleMode() { component.setupAccessibleMode = function setupAccessibleMode() {
@ -1233,8 +1252,11 @@ wp.mediaWidgets = ( function( $ ) {
* the widgets admin screen and also via the 'widget-synced' event when making * the widgets admin screen and also via the 'widget-synced' event when making
* a change to a widget in the customizer. * a change to a widget in the customizer.
* *
* @memberOf wp.mediaWidgets
*
* @param {jQuery.Event} event - Event. * @param {jQuery.Event} event - Event.
* @param {jQuery} widgetContainer - Widget container element. * @param {jQuery} widgetContainer - Widget container element.
*
* @returns {void} * @returns {void}
*/ */
component.handleWidgetUpdated = function handleWidgetUpdated( event, widgetContainer ) { component.handleWidgetUpdated = function handleWidgetUpdated( event, widgetContainer ) {
@ -1267,6 +1289,8 @@ wp.mediaWidgets = ( function( $ ) {
* When WordPress enqueues this script, it should have an inline script * When WordPress enqueues this script, it should have an inline script
* attached which calls wp.mediaWidgets.init(). * attached which calls wp.mediaWidgets.init().
* *
* @memberOf wp.mediaWidgets
*
* @returns {void} * @returns {void}
*/ */
component.init = function init() { component.init = function init() {

31
src/wp-admin/js/widgets/text-widgets.js
View File

@ -1,5 +1,9 @@
/* global tinymce, switchEditors */ /* global tinymce, switchEditors */
/* eslint consistent-this: [ "error", "control" ] */ /* eslint consistent-this: [ "error", "control" ] */
/**
* @namespace wp.textWidgets
*/
wp.textWidgets = ( function( $ ) { wp.textWidgets = ( function( $ ) {
'use strict'; 'use strict';
@ -8,14 +12,7 @@ wp.textWidgets = ( function( $ ) {
idBases: [ 'text' ] idBases: [ 'text' ]
}; };
/** component.TextWidgetControl = Backbone.View.extend(/** @lends wp.textWidgets.TextWidgetControl.prototype */{
* Text widget control.
*
* @class TextWidgetControl
* @constructor
* @abstract
*/
component.TextWidgetControl = Backbone.View.extend({
/** /**
* View events. * View events.
@ -25,11 +22,16 @@ wp.textWidgets = ( function( $ ) {
events: {}, events: {},
/** /**
* Initialize. * Text widget control.
*
* @constructs wp.textWidgets.TextWidgetControl
* @augments Backbone.View
* @abstract
* *
* @param {Object} options - Options. * @param {Object} options - Options.
* @param {jQuery} options.el - Control field container element. * @param {jQuery} options.el - Control field container element.
* @param {jQuery} options.syncContainer - Container element where fields are synced for the server. * @param {jQuery} options.syncContainer - Container element where fields are synced for the server.
*
* @returns {void} * @returns {void}
*/ */
initialize: function initialize( options ) { initialize: function initialize( options ) {
@ -357,6 +359,8 @@ wp.textWidgets = ( function( $ ) {
/** /**
* Mapping of widget ID to instances of TextWidgetControl subclasses. * Mapping of widget ID to instances of TextWidgetControl subclasses.
* *
* @memberOf wp.textWidgets
*
* @type {Object.<string, wp.textWidgets.TextWidgetControl>} * @type {Object.<string, wp.textWidgets.TextWidgetControl>}
*/ */
component.widgetControls = {}; component.widgetControls = {};
@ -364,8 +368,11 @@ wp.textWidgets = ( function( $ ) {
/** /**
* Handle widget being added or initialized for the first time at the widget-added event. * Handle widget being added or initialized for the first time at the widget-added event.
* *
* @memberOf wp.textWidgets
*
* @param {jQuery.Event} event - Event. * @param {jQuery.Event} event - Event.
* @param {jQuery} widgetContainer - Widget container element. * @param {jQuery} widgetContainer - Widget container element.
*
* @returns {void} * @returns {void}
*/ */
component.handleWidgetAdded = function handleWidgetAdded( event, widgetContainer ) { component.handleWidgetAdded = function handleWidgetAdded( event, widgetContainer ) {
@ -429,6 +436,8 @@ wp.textWidgets = ( function( $ ) {
/** /**
* Setup widget in accessibility mode. * Setup widget in accessibility mode.
* *
* @memberOf wp.textWidgets
*
* @returns {void} * @returns {void}
*/ */
component.setupAccessibleMode = function setupAccessibleMode() { component.setupAccessibleMode = function setupAccessibleMode() {
@ -467,6 +476,8 @@ wp.textWidgets = ( function( $ ) {
* the widgets admin screen and also via the 'widget-synced' event when making * the widgets admin screen and also via the 'widget-synced' event when making
* a change to a widget in the customizer. * a change to a widget in the customizer.
* *
* @memberOf wp.textWidgets
*
* @param {jQuery.Event} event - Event. * @param {jQuery.Event} event - Event.
* @param {jQuery} widgetContainer - Widget container element. * @param {jQuery} widgetContainer - Widget container element.
* @returns {void} * @returns {void}
@ -496,6 +507,8 @@ wp.textWidgets = ( function( $ ) {
* When WordPress enqueues this script, it should have an inline script * When WordPress enqueues this script, it should have an inline script
* attached which calls wp.textWidgets.init(). * attached which calls wp.textWidgets.init().
* *
* @memberOf wp.textWidgets
*
* @returns {void} * @returns {void}
*/ */
component.init = function init() { component.init = function init() {

6
src/wp-includes/js/comment-reply.js
View File

@ -3,6 +3,8 @@
* *
* @since 2.7.0 * @since 2.7.0
* *
* @namespace addComment
*
* @type {Object} * @type {Object}
*/ */
var addComment; var addComment;
@ -50,6 +52,8 @@ addComment = ( function( window ) {
* *
* @since 5.0.0 * @since 5.0.0
* *
* @memberOf addComment
*
* @param {HTMLElement} context The parent DOM element to search for links. * @param {HTMLElement} context The parent DOM element to search for links.
*/ */
function init( context ) { function init( context ) {
@ -199,6 +203,8 @@ addComment = ( function( window ) {
* *
* @since 2.7.0 * @since 2.7.0
* *
* @memberOf addComment
*
* @param {String} addBelowId HTML ID of element the form follows. * @param {String} addBelowId HTML ID of element the form follows.
* @param {String} commentId Database ID of comment being replied to. * @param {String} commentId Database ID of comment being replied to.
* @param {String} respondId HTML ID of 'respond' element. * @param {String} respondId HTML ID of 'respond' element.

5
src/wp-includes/js/customize-base.js
View File

@ -908,7 +908,7 @@ window.wp = window.wp || {};
/** /**
* Get all customize settings. * Get all customize settings.
* *
* @memberOf wp.customize * @alias wp.customize.get
* *
* @return {object} * @return {object}
*/ */
@ -934,7 +934,8 @@ window.wp = window.wp || {};
* *
* @since 4.7.0 * @since 4.7.0
* @access public * @access public
* @memberOf wp.customize.utils *
* @alias wp.customize.utils.parseQueryString
* *
* @param {string} queryString Query string. * @param {string} queryString Query string.
* @returns {object} Parsed query string. * @returns {object} Parsed query string.

3
src/wp-includes/js/media/views/frame/post.js
View File

@ -445,7 +445,8 @@ Post = Select.extend(/** @lends wp.media.view.MediaFrame.Post.prototype */{
requires: { selection: true }, requires: { selection: true },
/** /**
* @callback * @ignore
*
* @fires wp.media.controller.State#insert * @fires wp.media.controller.State#insert
*/ */
click: function() { click: function() {

6
src/wp-includes/js/mediaelement/wp-mediaelement.js
View File

@ -12,6 +12,8 @@
* Ensures media elements that have already been initialized won't be * Ensures media elements that have already been initialized won't be
* processed again. * processed again.
* *
* @memberOf wp.mediaelement
*
* @since 4.4.0 * @since 4.4.0
* *
* @returns {void} * @returns {void}
@ -56,6 +58,10 @@
}; };
} }
/**
* @namespace wp.mediaelement
* @memberOf wp
*/
window.wp.mediaelement = new wpMediaElement(); window.wp.mediaelement = new wpMediaElement();
$( window.wp.mediaelement.initialize ); $( window.wp.mediaelement.initialize );

12
src/wp-includes/js/mediaelement/wp-playlist.js
View File

@ -3,7 +3,13 @@
(function ($, _, Backbone) { (function ($, _, Backbone) {
'use strict'; 'use strict';
var WPPlaylistView = Backbone.View.extend({ var WPPlaylistView = Backbone.View.extend(/** @lends WPPlaylistView.prototype */{
/**
* @constructs
*
* @param {Object} options The options to create this playlist view with.
* @param {Object} options.metadata The metadata
*/
initialize : function (options) { initialize : function (options) {
this.index = 0; this.index = 0;
this.settings = {}; this.settings = {};
@ -59,9 +65,7 @@
this.settings.success = this.bindResetPlayer; this.settings.success = this.bindResetPlayer;
} }
/** // This is also our bridge to the outside world.
* This is also our bridge to the outside world
*/
this.player = new MediaElementPlayer( this.playerNode.get(0), this.settings ); this.player = new MediaElementPlayer( this.playerNode.get(0), this.settings );
}, },

7
src/wp-includes/js/plupload/wp-plupload.js
View File

@ -1,5 +1,8 @@
/* global pluploadL10n, plupload, _wpPluploadSettings */ /* global pluploadL10n, plupload, _wpPluploadSettings */
/**
* @namespace wp
*/
window.wp = window.wp || {}; window.wp = window.wp || {};
( function( exports, $ ) { ( function( exports, $ ) {
@ -16,6 +19,10 @@ window.wp = window.wp || {};
* This object bridges the Plupload API to integrate uploads into the * This object bridges the Plupload API to integrate uploads into the
* WordPress back end and the WordPress media experience. * WordPress back end and the WordPress media experience.
* *
* @class
* @memberOf wp
* @alias wp.Uploader
*
* @param {object} options The options passed to the new plupload instance. * @param {object} options The options passed to the new plupload instance.
* @param {object} options.container The id of uploader container. * @param {object} options.container The id of uploader container.
* @param {object} options.browser The id of button to trigger the file select. * @param {object} options.browser The id of button to trigger the file select.

2
src/wp-includes/js/wp-api.js
View File

@ -1161,7 +1161,7 @@
* have to retrieve it again for this session. Then, construct the models and collections based * have to retrieve it again for this session. Then, construct the models and collections based
* on the schema model data. * on the schema model data.
* *
* @callback * @ignore
*/ */
success: function( newSchemaModel ) { success: function( newSchemaModel ) {