sergiotarxz/Wordpress
1
0
Fork 0
Code Issues Pull Requests 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": [],
"recurseDepth": 10,
"source": {
"include": ["src/wp-includes/js"],
"include": [
"src/wp-includes/js",
"src/wp-admin/js"
],
"exclude": [
"src/wp-includes/js/codemirror",
"src/wp-includes/js/tinymce",
"src/wp-includes/js/crop",
"src/wp-includes/js/imgareaselect",
"src/wp-includes/js/jcrop",
"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/thickbox",
"src/wp-includes/js/media-audiovideo.js",
@ -35,6 +44,7 @@
},
"opts": {
"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 ) {
/**
* @namespace wp
*/
window.wp = {};
}
if ( 'undefined' === typeof window.wp.codeEditor ) {
/**
* @namespace wp.codeEditor
*/
window.wp.codeEditor = {};
}
@ -33,6 +39,7 @@ if ( 'undefined' === typeof window.wp.codeEditor ) {
* @param {object} settings.codeMirror - Settings for CodeMirror.
* @param {Function} settings.onChangeLintingErrors - Callback for when there are changes to linting errors.
* @param {Function} settings.onUpdateErrorNotice - Callback to update error notice.
*
* @returns {void}
*/
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 {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.
*
* @returns {void}
*/
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 {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.htmlhint] - Rules for HTMLHint.
* @param {object} [settings.jshint] - Rules for JSHint.
*
* @returns {CodeEditorInstance} Instance.
*/
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.
*
* @class $.widget.wp.wpColorPicker
*
* @since 3.5.0
*/
ColorPicker = {
ColorPicker = /** @lends $.widget.wp.wpColorPicker.prototype */{
options: {
defaultColor: false,
change: false,
@ -56,6 +58,8 @@
/**
* @summary Handles the onChange event if one has been defined in the options.
*
* @ignore
*
* @param {Event} event The event that's being called.
* @param {HTMLElement} ui The HTMLElement containing the color picker.
*
@ -179,6 +183,8 @@
*
* @since 3.5.0
*
* @ignore
*
* @param {Event} event The event that's being called.
* @param {HTMLElement} ui The HTMLElement containing the color picker.
*

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

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

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

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

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

@ -7,6 +7,9 @@
var api = wp.customize,
l10n;
/**
* @namespace wp.customize.Widgets
*/
api.Widgets = api.Widgets || {};
api.Widgets.savedWidgetIds = {};
@ -19,10 +22,10 @@
*
* A single widget model.
*
* @constructor
* @class wp.customize.Widgets.WidgetModel
* @augments Backbone.Model
*/
api.Widgets.WidgetModel = Backbone.Model.extend({
api.Widgets.WidgetModel = Backbone.Model.extend(/** @lends wp.customize.Widgets.WidgetModel.prototype */{
id: null,
temp_id: null,
classname: null,
@ -45,10 +48,10 @@
*
* Collection for widget models.
*
* @constructor
* @augments Backbone.Model
* @class wp.customize.Widgets.WidgetCollection
* @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,
// Controls searching on the current widget collection
@ -103,10 +106,10 @@
*
* A single sidebar model.
*
* @constructor
* @class wp.customize.Widgets.SidebarModel
* @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_widget: null,
before_title: null,
@ -123,24 +126,15 @@
*
* Collection for sidebar models.
*
* @constructor
* @class wp.customize.Widgets.SidebarCollection
* @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
});
api.Widgets.registeredSidebars = new api.Widgets.SidebarCollection( api.Widgets.data.registeredSidebars );
/**
* 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({
api.Widgets.AvailableWidgetsPanelView = wp.Backbone.View.extend(/** @lends wp.customize.Widgets.AvailableWidgetsPanelView.prototype */{
el: '#available-widgets',
@ -162,6 +156,12 @@
$clearResults: null,
searchMatchesCount: null,
/**
* View class for the available widgets panel.
*
* @constructs wp.customize.Widgets.AvailableWidgetsPanelView
* @augments wp.Backbone.View
*/
initialize: function() {
var self = this;
@ -197,7 +197,9 @@
api.previewer.bind( 'url', this.close );
},
// Performs a search and handles selected widget
/**
* Performs a search and handles selected widget.
*/
search: function( event ) {
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() {
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() {
var message = l10n.widgetsFound.replace( '%d', this.searchMatchesCount ) ;
@ -258,7 +264,9 @@
wp.a11y.speak( message );
}, 500 ),
// Changes visibility of available widgets
/**
* Changes visibility of available widgets.
*/
updateList: function() {
this.collection.each( function( widget ) {
var widgetTpl = $( '#widget-tpl-' + widget.id );
@ -269,19 +277,25 @@
} );
},
// Highlights a widget
/**
* Highlights a widget.
*/
select: function( widgetTpl ) {
this.selected = $( widgetTpl );
this.selected.siblings( '.widget-tpl' ).removeClass( 'selected' );
this.selected.addClass( 'selected' );
},
// Highlights a widget on focus
/**
* Highlights a widget on focus.
*/
focus: function( event ) {
this.select( $( event.currentTarget ) );
},
// Submit handler for keypress and click on widget
/**
* Handles submit for keypress and click on widget.
*/
_submit: function( event ) {
// Only proceed with keypress if it is Enter or Spacebar
if ( event.type === 'keypress' && ( event.which !== 13 && event.which !== 32 ) ) {
@ -291,7 +305,9 @@
this.submit( $( event.currentTarget ) );
},
// Adds a selected widget to the sidebar
/**
* Adds a selected widget to the sidebar.
*/
submit: function( widgetTpl ) {
var widgetId, widget, widgetFormControl;
@ -319,7 +335,9 @@
this.close();
},
// Opens the panel
/**
* Opens the panel.
*/
open: function( sidebarControl ) {
this.currentSidebarControl = sidebarControl;
@ -346,7 +364,9 @@
}
},
// Closes the panel
/**
* Closes the panel.
*/
close: function( options ) {
options = options || {};
@ -362,7 +382,9 @@
this.$search.val( '' );
},
// Add keyboard accessiblity to the panel
/**
* Adds keyboard accessiblity to the panel.
*/
keyboardAccessible: function( event ) {
var isEnter = ( event.which === 13 ),
isEsc = ( event.which === 27 ),
@ -424,6 +446,8 @@
* Handlers for the widget-synced event, organized by widget ID base.
* Other widgets may provide their own update handlers by adding
* listeners for the widget-synced event.
*
* @alias wp.customize.Widgets.formSyncHandlers
*/
api.Widgets.formSyncHandlers = {
@ -446,23 +470,22 @@
}
};
/**
* 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({
api.Widgets.WidgetControl = api.Control.extend(/** @lends wp.customize.Widgets.WidgetControl.prototype */{
defaultExpandedArguments: {
duration: 'fast',
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
*
* @constructs wp.customize.Widgets.WidgetControl
* @augments wp.customize.Control
*/
initialize: function( id, options ) {
var control = this;
@ -943,7 +966,7 @@
*
* @param {Boolean} active
* @param {Object} args
* @param {Callback} args.completeCallback
* @param {function} args.completeCallback
*/
onChangeActive: function ( active, args ) {
// 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.
*
* @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.
@ -1695,8 +1721,11 @@
* Customizer section representing a widget area widget
*
* @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
@ -1722,10 +1751,10 @@
*
* @since 3.9.0
*
* @constructor
* @class wp.customize.Widgets.SidebarControl
* @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

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.
*
* @namespace 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.
*
* @ignore
*
* @param {jQuery} img The preview image.
*/
onInit: function( img ) {
@ -645,6 +647,8 @@
/**
* @summary Event triggered when starting a selection.
*
* @ignore
*
* @returns {void}
*/
onSelectStart: function() {
@ -653,6 +657,8 @@
/**
* @summary Event triggered when the selection is ended.
*
* @ignore
*
* @param {object} img jQuery object representing the image.
* @param {object} c The selection.
*
@ -665,6 +671,8 @@
/**
* @summary Event triggered when the selection changes.
*
* @ignore
*
* @param {object} img jQuery object representing the image.
* @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.
*
* @namespace
* @namespace inlineEditPost
*
* @since 2.7.0
* @access public
*
* @type {Object}
*

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

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

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

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

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

@ -1,7 +1,7 @@
/* global plugininstallL10n, tb_click, tb_remove */
/**
* Functionality for the plugin install screens.
* @file Functionality for the plugin install screens.
*/
var tb_position;
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.
*
* @summary Control page and term functionality.
* @file Control page and term functionality.
*/
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.
*
* @memberof commentsBox
*
* @param {int} total Total number of comments for this post.
* @param {int} num Optional. Number of comments to fetch, defaults to 20.
* @returns {boolean} Always returns false.
*
* @memberof commentsBox
*/
get : function(total, num) {
var st = this.st, data;
@ -662,6 +662,8 @@ jQuery(document).ready( function($) {
/**
* Add current post_ID to request to fetch custom fields
*
* @ignore
*
* @param {Object} s Request object.
*
* @returns {Object} Data modified with post_ID attached.
@ -672,6 +674,8 @@ jQuery(document).ready( function($) {
},
/**
* Show the listing of custom fields after fetching.
*
* @ignore
*/
addAfter: function() {
$('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.
*
* @ignore
*
* @returns void
*/
updateVisibility = function() {
@ -711,6 +717,8 @@ jQuery(document).ready( function($) {
/**
* Make sure all labels represent the current settings.
*
* @ignore
*
* @returns {boolean} False when an invalid timestamp has been selected, otherwise True.
*/
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.
*
* @since 4.0.0
* @ignore
*
* @event postboxes#postbox-toggled
* @type {Object}
*/
@ -137,6 +139,8 @@ var postboxes;
* clicked this function will hide or show the relevant postboxes.
*
* @since 2.7.0
* @ignore
*
* @fires postboxes#postbox-toggled
*
* @returns {void}
@ -383,6 +387,8 @@ var postboxes;
* Fires when the amount of columns on the post edit page has been changed.
*
* @since 4.0.0
* @ignore
*
* @event postboxes#postboxes-columnchange
*/
$( document ).trigger( 'postboxes-columnchange' );

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

@ -2,9 +2,6 @@
* Functions for ajaxified updates, deletions and installs inside the WordPress admin.
*
* @version 4.2.0
*
* @package WordPress
* @subpackage Administration
*/
/* global pagenow */
@ -38,7 +35,7 @@
*
* @since 4.2.0
*
* @type {object}
* @namespace wp.updates
*/
wp.updates = {};
@ -84,19 +81,19 @@
* @since 4.2.0
* @since 4.6.0 Added `available` property to indicate whether credentials have been provided.
*
* @type {object} filesystemCredentials Holds filesystem credentials.
* @type {object} filesystemCredentials.ftp Holds FTP credentials.
* @type {string} filesystemCredentials.ftp.host FTP host. Default empty string.
* @type {string} filesystemCredentials.ftp.username FTP user name. Default empty string.
* @type {string} filesystemCredentials.ftp.password FTP password. Default empty string.
* @type {string} filesystemCredentials.ftp.connectionType Type of FTP connection. 'ssh', 'ftp', or 'ftps'.
* Default empty string.
* @type {object} filesystemCredentials.ssh Holds SSH credentials.
* @type {string} filesystemCredentials.ssh.publicKey The public key. Default empty string.
* @type {string} filesystemCredentials.ssh.privateKey The private key. Default empty string.
* @type {string} filesystemCredentials.fsNonce Filesystem credentials form nonce.
* @type {bool} filesystemCredentials.available Whether filesystem credentials have been provided.
* Default 'false'.
* @type {Object}
* @property {Object} filesystemCredentials.ftp Holds FTP credentials.
* @property {string} filesystemCredentials.ftp.host FTP host. Default empty string.
* @property {string} filesystemCredentials.ftp.username FTP user name. Default empty string.
* @property {string} filesystemCredentials.ftp.password FTP password. Default empty string.
* @property {string} filesystemCredentials.ftp.connectionType Type of FTP connection. 'ssh', 'ftp', or 'ftps'.
* Default empty string.
* @property {Object} filesystemCredentials.ssh Holds SSH credentials.
* @property {string} filesystemCredentials.ssh.publicKey The public key. Default empty string.
* @property {string} filesystemCredentials.ssh.privateKey The private key. Default empty string.
* @property {string} filesystemCredentials.fsNonce Filesystem credentials form nonce.
* @property {bool} filesystemCredentials.available Whether filesystem credentials have been provided.
* Default 'false'.
*/
wp.updates.filesystemCredentials = {
ftp: {
@ -128,7 +125,7 @@
*
* @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' );
@ -407,7 +404,6 @@
* @since 4.2.0
* @since 4.6.0 More accurately named `updatePluginSuccess`.
*
* @typedef {object} updatePluginSuccess
* @param {object} response Response from the server.
* @param {string} response.slug Slug 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.6.0 More accurately named `updatePluginError`.
*
* @typedef {object} updatePluginError
* @param {object} response Response from the server.
* @param {string} response.slug Slug 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
*
* @typedef {object} installPluginSuccess
* @param {object} response Response from the server.
* @param {string} response.slug Slug of the installed plugin.
* @param {string} response.pluginName Name of the installed plugin.
@ -610,7 +604,6 @@
*
* @since 4.6.0
*
* @typedef {object} installPluginError
* @param {object} response Response from the server.
* @param {string} response.slug Slug 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
*
* @typedef {object} installImporterSuccess
* @param {object} response Response from the server.
* @param {string} response.slug Slug of the installed plugin.
* @param {string} response.pluginName Name of the installed plugin.
@ -693,7 +685,6 @@
*
* @since 4.6.0
*
* @typedef {object} installImporterError
* @param {object} response Response from the server.
* @param {string} response.slug Slug 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
*
* @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.plugin Base name of the plugin that was deleted.
* @param {string} response.pluginName Name of the plugin that was deleted.
@ -783,7 +773,11 @@
$pluginRow = $( this ),
columnCount = $form.find( 'thead th:not(.hidden), thead td' ).length,
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;
// Add a success message after deleting a plugin.
@ -858,7 +852,6 @@
*
* @since 4.6.0
*
* @typedef {object} deletePluginError
* @param {object} response Response from the server.
* @param {string} response.slug Slug 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
*
* @typedef {object} updateThemeSuccess
* @param {object} response
* @param {string} response.slug Slug of the theme to be updated.
* @param {object} response.theme Updated theme.
@ -1033,7 +1025,6 @@
*
* @since 4.6.0
*
* @typedef {object} updateThemeError
* @param {object} response Response from the server.
* @param {string} response.slug Slug of the theme to be updated.
* @param {string} response.errorCode Error code for the error that occurred.
@ -1119,7 +1110,6 @@
*
* @since 4.6.0
*
* @typedef {object} installThemeSuccess
* @param {object} response Response from the server.
* @param {string} response.slug Slug of the theme to be installed.
* @param {string} response.customizeUrl URL to the Customizer for the just installed theme.
@ -1170,7 +1160,6 @@
*
* @since 4.6.0
*
* @typedef {object} installThemeError
* @param {object} response Response from the server.
* @param {string} response.slug Slug of the theme to be installed.
* @param {string} response.errorCode Error code for the error that occurred.
@ -1268,7 +1257,6 @@
*
* @since 4.6.0
*
* @typedef {object} deleteThemeSuccess
* @param {object} response Response from the server.
* @param {string} response.slug Slug of the theme that was deleted.
*/
@ -1327,7 +1315,6 @@
*
* @since 4.6.0
*
* @typedef {object} deleteThemeError
* @param {object} response Response from the server.
* @param {string} response.slug Slug of the theme to be deleted.
* @param {string} response.errorCode Error code for the error that occurred.
@ -1601,7 +1588,6 @@
*
* @since 4.6.0
*
* @typedef {object} maybeHandleCredentialError
* @param {object} response Response from the server.
* @param {string} response.errorCode Error code for 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.
*
* @ignore
*
* @param {object} event jQuery event object.
*/
over: function( event ) {
@ -268,6 +270,8 @@ wpWidgets = {
/**
* Close Sidebar when the Widget gets dragged out of it.
*
* @ignore
*
* @param {object} event jQuery event object.
*/
out: function( event ) {

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

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

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

@ -8,10 +8,10 @@
* Custom gallery details frame.
*
* @since 4.9.0
* @class GalleryDetailsMediaFrame
* @constructor
* @class wp.mediaWidgets~GalleryDetailsMediaFrame
* @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.
@ -53,21 +53,13 @@
* See WP_Widget_Gallery::enqueue_admin_scripts() for amending prototype from PHP exports.
*
* @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 */{} );
/**
* 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( {
GalleryWidgetControl = component.MediaWidgetControl.extend(/** @lends wp.mediaWidgets.controlConstructors.media_gallery.prototype */{
/**
* 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
* @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.
*
* @class ImageWidgetModel
* @constructor
* @class wp.mediaWidgets.modelConstructors.media_image
* @augments wp.mediaWidgets.MediaWidgetModel
*/
ImageWidgetModel = component.MediaWidgetModel.extend({});
@ -19,10 +19,10 @@
*
* See WP_Widget_Media_Image::enqueue_admin_scripts() for amending prototype from PHP exports.
*
* @class ImageWidgetModel
* @constructor
* @class wp.mediaWidgets.controlConstructors.media_audio
* @augments wp.mediaWidgets.MediaWidgetControl
*/
ImageWidgetControl = component.MediaWidgetControl.extend({
ImageWidgetControl = component.MediaWidgetControl.extend(/** @lends wp.mediaWidgets.controlConstructors.media_image.prototype */{
/**
* 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.
*
* @class VideoDetailsMediaFrame
* @constructor
* @class wp.mediaWidgets.controlConstructors~VideoDetailsMediaFrame
* @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.
@ -49,8 +51,8 @@
*
* See WP_Widget_Video::enqueue_admin_scripts() for amending prototype from PHP exports.
*
* @class VideoWidgetModel
* @constructor
* @class wp.mediaWidgets.modelConstructors.media_video
* @augments wp.mediaWidgets.MediaWidgetModel
*/
VideoWidgetModel = component.MediaWidgetModel.extend({});
@ -59,10 +61,10 @@
*
* See WP_Widget_Video::enqueue_admin_scripts() for amending prototype from PHP exports.
*
* @class VideoWidgetControl
* @constructor
* @class wp.mediaWidgets.controlConstructors.media_video
* @augments wp.mediaWidgets.MediaWidgetControl
*/
VideoWidgetControl = component.MediaWidgetControl.extend({
VideoWidgetControl = component.MediaWidgetControl.extend(/** @lends wp.mediaWidgets.controlConstructors.media_video.prototype */{
/**
* Show display settings.

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

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

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

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

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

@ -3,6 +3,8 @@
*
* @since 2.7.0
*
* @namespace addComment
*
* @type {Object}
*/
var addComment;
@ -50,6 +52,8 @@ addComment = ( function( window ) {
*
* @since 5.0.0
*
* @memberOf addComment
*
* @param {HTMLElement} context The parent DOM element to search for links.
*/
function init( context ) {
@ -199,6 +203,8 @@ addComment = ( function( window ) {
*
* @since 2.7.0
*
* @memberOf addComment
*
* @param {String} addBelowId HTML ID of element the form follows.
* @param {String} commentId Database ID of comment being replied to.
* @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.
*
* @memberOf wp.customize
* @alias wp.customize.get
*
* @return {object}
*/
@ -934,7 +934,8 @@ window.wp = window.wp || {};
*
* @since 4.7.0
* @access public
* @memberOf wp.customize.utils
*
* @alias wp.customize.utils.parseQueryString
*
* @param {string} queryString 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 },
/**
* @callback
* @ignore
*
* @fires wp.media.controller.State#insert
*/
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
* processed again.
*
* @memberOf wp.mediaelement
*
* @since 4.4.0
*
* @returns {void}
@ -56,6 +58,10 @@
};
}
/**
* @namespace wp.mediaelement
* @memberOf wp
*/
window.wp.mediaelement = new wpMediaElement();
$( window.wp.mediaelement.initialize );

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

@ -3,7 +3,13 @@
(function ($, _, Backbone) {
'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) {
this.index = 0;
this.settings = {};
@ -59,9 +65,7 @@
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 );
},

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

@ -1,5 +1,8 @@
/* global pluploadL10n, plupload, _wpPluploadSettings */
/**
* @namespace wp
*/
window.wp = window.wp || {};
( function( exports, $ ) {
@ -16,6 +19,10 @@ window.wp = window.wp || {};
* This object bridges the Plupload API to integrate uploads into the
* 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.container The id of uploader container.
* @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
* on the schema model data.
*
* @callback
* @ignore
*/
success: function( newSchemaModel ) {