Commit 7e7e14dd authored by Jake Spurlock's avatar Jake Spurlock
Browse files

Build/Test Tools: Enable JSDocs to be linted with ESLint. 

As part of the [Javascript Inline Docs Initiative](https://make.wordpress.org/core/handbook/docs/inline/js/) this add some tooling to lint Javascript docblocks. Two new commands:

* `npm run lint:jsdoc`
* `npm run lint:jsdoc:fix`

The latter will run the linter and try to fix an possible issues automatically.

Fixes #43828.
Props netweb, atimmer, kamataryo, whyisjake.


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


git-svn-id: https://core.svn.wordpress.org/trunk@48412 1a063a9b-81f0-0310-95a4-ce76da25c4cd
parent b6848871

wp-admin/js/code-editor.js

+10 −10
Original line number Diff line number Diff line
@@ -39,8 +39,8 @@ if ( 'undefined' === typeof window.wp.codeEditor ) { 
	 * Configure linting.

	 *

	 * @param {CodeMirror} editor - Editor.

	 * @param {object}     settings - Code editor settings.

	 * @param {object}     settings.codeMirror - Settings for CodeMirror.

	 * @param {Object}     settings - Code editor settings.

	 * @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.

	 *
@@ -64,7 +64,7 @@ if ( 'undefined' === typeof window.wp.codeEditor ) { 
		/**

		 * Get lint options.

		 *

		 * @return {object} Lint options.

		 * @return {Object} Lint options.

		 */

		function getLintOptions() { // eslint-disable-line complexity

			var options = editor.getOption( 'lint' );
@@ -213,8 +213,8 @@ if ( 'undefined' === typeof window.wp.codeEditor ) { 
	 * Configure tabbing.

	 *

	 * @param {CodeMirror} codemirror - Editor.

	 * @param {object}     settings - Code editor settings.

	 * @param {object}     settings.codeMirror - Settings for CodeMirror.

	 * @param {Object}     settings - Code editor settings.

	 * @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.

	 *
@@ -267,15 +267,15 @@ if ( 'undefined' === typeof window.wp.codeEditor ) { 
	 * @since 4.9.0

	 *

	 * @param {string|jQuery|Element} textarea - The HTML id, jQuery object, or DOM Element for the textarea that is used for the editor.

	 * @param {object}                [settings] - Settings to override defaults.

	 * @param {Object}                [settings] - Settings to override defaults.

	 * @param {Function}              [settings.onChangeLintingErrors] - Callback for when the linting errors have changed.

	 * @param {Function}              [settings.onUpdateErrorNotice] - Callback for when error notice should be displayed.

	 * @param {Function}              [settings.onTabPrevious] - Callback to handle tabbing to the previous tabbable element.

	 * @param {Function}              [settings.onTabNext] - Callback to handle tabbing to the next tabbable element.

	 * @param {object}                [settings.codemirror] - Options for CodeMirror.

	 * @param {object}                [settings.csslint] - Rules for CSSLint.

	 * @param {object}                [settings.htmlhint] - Rules for HTMLHint.

	 * @param {object}                [settings.jshint] - Rules for JSHint.

	 * @param {Object}                [settings.codemirror] - Options for CodeMirror.

	 * @param {Object}                [settings.csslint] - Rules for CSSLint.

	 * @param {Object}                [settings.htmlhint] - Rules for HTMLHint.

	 * @param {Object}                [settings.jshint] - Rules for JSHint.

	 *

	 * @return {CodeEditorInstance} Instance.

	 */

wp-admin/js/common.js

+2 −2
Original line number Diff line number Diff line
@@ -137,7 +137,7 @@ window.columns = { 
	 *

	 * @since 3.1.0

	 *

	 * @param {int} diff The modifier for the column span.

	 * @param {number} diff The modifier for the column span.

	 */

	colSpanChange : function(diff) {

		var $t = $('table').find('.colspanchange'), n;
@@ -384,7 +384,7 @@ $permalinkStructure.on( 'focus', function( event ) { 
 * If the structure is already used in the custom permalink structure,

 * it will be disabled.

 *

 * @param {object} button Button jQuery object.

 * @param {Object} button Button jQuery object.

 */

function changeStructureTagButtonState( button ) {

	if ( -1 !== $permalinkStructure.val().indexOf( button.text().trim() ) ) {

wp-admin/js/customize-controls.js

+92 −92

File changed.

Preview size limit exceeded, changes collapsed.

wp-admin/js/customize-nav-menus.js

+13 −13
Original line number Diff line number Diff line
@@ -95,7 +95,7 @@ 
	 * @since 4.7.0

	 * @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_title - Post title to use.

	 * @return {jQuery.promise} Promise resolved with the added post.
@@ -387,7 +387,7 @@ 
		 * @since 4.7.0 Changed function signature to take list of item types instead of single type/object.

		 * @access private

		 *

		 * @param {Array.<object>} itemTypes List of objects containing type and key.

		 * @param {Array.<Object>} itemTypes List of objects containing type and key.

		 * @param {string} deprecated Formerly the object parameter.

		 * @return {void}

		 */
@@ -905,7 +905,7 @@ 
		 *

		 * @since 4.3.0

		 *

		 * @param {String} id

		 * @param {string} id

		 * @param {Object} options

		 */

		initialize: function( id, options ) {
@@ -2212,7 +2212,7 @@ 
		 *

		 * @private

		 *

		 * @param {Number} offset 1|-1

		 * @param {number} offset 1|-1

		 */

		_changePosition: function( offset ) {

			var control = this,
@@ -2272,7 +2272,7 @@ 
		 *

		 * @private

		 *

		 * @param {Number} offset 1|-1

		 * @param {number} offset 1|-1

		 */

		_changeDepth: function( offset ) {

			if ( 1 !== offset && -1 !== offset ) {
@@ -2655,7 +2655,7 @@ 
		 * Notice that the UI aspects here are handled by wpNavMenu.initSortables()

		 * which is called in MenuSection.onChangeExpanded()

		 *

		 * @param {object} menuList - The element that has sortable().

		 * @param {Object} menuList - The element that has sortable().

		 */

		_setupSortable: function( menuList ) {

			var control = this;
@@ -2854,7 +2854,7 @@ 
		/**

		 * Enable/disable the reordering UI

		 *

		 * @param {Boolean} showOrHide to enable/disable reordering

		 * @param {boolean} showOrHide to enable/disable reordering

		 */

		toggleReordering: function( showOrHide ) {

			var addNewItemBtn = this.container.find( '.add-new-menu-item' ),
@@ -2994,7 +2994,7 @@ 
		/**

		 * Add a new item to this menu.

		 *

		 * @param {object} item - Value for the nav_menu_item setting to be created.

		 * @param {Object} item - Value for the nav_menu_item setting to be created.

		 * @return {wp.customize.Menus.controlConstructor.nav_menu_item} The newly-created nav_menu_item control instance.

		 */

		addItemToMenu: function( item ) {
@@ -3135,9 +3135,9 @@ 
	 *

	 * @alias wp.customize.Menus.applySavedData

	 *

	 * @param {object} data

	 * @param {array} data.nav_menu_updates

	 * @param {array} data.nav_menu_item_updates

	 * @param {Object} data

	 * @param {Array} data.nav_menu_updates

	 * @param {Array} data.nav_menu_item_updates

	 */

	api.Menus.applySavedData = function( data ) {
@@ -3394,7 +3394,7 @@ 
	 * @alias wp.customize.Menus.getMenuItemControl

	 *

	 * @param {string} menuItemId

	 * @return {object|null}

	 * @return {Object|null}

	 */

	api.Menus.getMenuItemControl = function( menuItemId ) {

		return api.control( menuItemIdToSettingId( menuItemId ) );
@@ -3403,7 +3403,7 @@ 
	/**

	 * @alias wp.customize.Menus~menuItemIdToSettingId

	 *

	 * @param {String} menuItemId

	 * @param {string} menuItemId

	 */

	function menuItemIdToSettingId( menuItemId ) {

		return 'nav_menu_item[' + menuItemId + ']';

wp-admin/js/customize-widgets.js

+17 −17
Original line number Diff line number Diff line
@@ -459,7 +459,7 @@ 
		/**

		 * @param {jQuery.Event} e

		 * @param {jQuery} widget

		 * @param {String} newForm

		 * @param {string} newForm

		 */

		rss: function( e, widget, newForm ) {

			var oldWidgetError = widget.find( '.widget-error:first' ),
@@ -968,7 +968,7 @@ 
		 *

		 * @since 4.1.0

		 *

		 * @param {Boolean}   active

		 * @param {boolean}   active

		 * @param {Object}    args

		 * @param {function}  args.completeCallback

		 */
@@ -1075,7 +1075,7 @@ 
		 * Get the state for an input depending on its type.

		 *

		 * @param {jQuery|Element} input

		 * @return {string|boolean|array|*}

		 * @return {string|boolean|Array|*}

		 * @private

		 */

		_getInputState: function( input ) {
@@ -1095,7 +1095,7 @@ 
		 * Update an input's state based on its type.

		 *

		 * @param {jQuery|Element} input

		 * @param {string|boolean|array|*} state

		 * @param {string|boolean|Array|*} state

		 * @private

		 */

		_setInputState: function ( input, state ) {
@@ -1143,10 +1143,10 @@ 
		 * Submit the widget form via Ajax and get back the updated instance,

		 * along with the new widget control form to render.

		 *

		 * @param {object} [args]

		 * @param {Object} [args]

		 * @param {Object|null} [args.instance=null]  When the model changes, the instance is sent here; otherwise, the inputs from the form are used

		 * @param {Function|null} [args.complete=null]  Function which is called when the request finishes. Context is bound to the control. First argument is any error. Following arguments are for success.

		 * @param {Boolean} [args.ignoreActiveElement=false] Whether or not updating a field will be deferred if focus is still on the element.

		 * @param {boolean} [args.ignoreActiveElement=false] Whether or not updating a field will be deferred if focus is still on the element.

		 */

		updateWidget: function( args ) {

			var self = this, instanceOverride, completeCallback, $widgetRoot, $widgetContent,
@@ -1398,7 +1398,7 @@ 
		/**

		 * Respond to change in the expanded state.

		 *

		 * @param {Boolean} expanded

		 * @param {boolean} expanded

		 * @param {Object} args  merged on top of this.defaultActiveArguments

		 */

		onChangeExpanded: function ( expanded, args ) {
@@ -1498,7 +1498,7 @@ 
		/**

		 * Get the position (index) of the widget in the containing sidebar

		 *

		 * @return {Number}

		 * @return {number}

		 */

		getWidgetSidebarPosition: function() {

			var sidebarWidgetIds, position;
@@ -1530,7 +1530,7 @@ 
		/**

		 * @private

		 *

		 * @param {Number} offset 1|-1

		 * @param {number} offset 1|-1

		 */

		_moveWidgetByOne: function( offset ) {

			var i, sidebarWidgetsSetting, sidebarWidgetIds,	adjacentWidgetId;
@@ -1549,7 +1549,7 @@ 
		/**

		 * Toggle visibility of the widget move area

		 *

		 * @param {Boolean} [showOrHide]

		 * @param {boolean} [showOrHide]

		 */

		toggleWidgetMoveArea: function( showOrHide ) {

			var self = this, $moveWidgetArea;
@@ -2007,7 +2007,7 @@ 
		/**

		 * Enable/disable the reordering UI

		 *

		 * @param {Boolean} showOrHide to enable/disable reordering

		 * @param {boolean} showOrHide to enable/disable reordering

		 *

		 * @todo We should have a reordering state instead and rename this to onChangeReordering

		 */
@@ -2065,7 +2065,7 @@ 


		/**

		 * @param {string} widgetId or an id_base for adding a previously non-existing widget.

		 * @return {object|false} widget_form control instance, or false on error.

		 * @return {Object|false} widget_form control instance, or false on error.

		 */

		addWidget: function( widgetId ) {

			var self = this, controlHtml, $widget, controlType = 'widget_form', controlContainer, controlConstructor,
@@ -2246,7 +2246,7 @@ 
	/**

	 * Given a widget control, find the sidebar widgets control that contains it.

	 * @param {string} widgetId

	 * @return {object|null}

	 * @return {Object|null}

	 */

	api.Widgets.getSidebarWidgetControlContainingWidget = function( widgetId ) {

		var foundControl = null;
@@ -2265,7 +2265,7 @@ 
	 * Given a widget ID for a widget appearing in the preview, get the widget form control associated with it.

	 *

	 * @param {string} widgetId

	 * @return {object|null}

	 * @return {Object|null}

	 */

	api.Widgets.getWidgetFormControlForWidget = function( widgetId ) {

		var foundControl = null;
@@ -2333,7 +2333,7 @@ 
	}



	/**

	 * @param {String} widgetId

	 * @param {string} widgetId

	 * @return {Object}

	 */

	function parseWidgetId( widgetId ) {
@@ -2355,8 +2355,8 @@ 
	}



	/**

	 * @param {String} widgetId

	 * @return {String} settingId

	 * @param {string} widgetId

	 * @return {string} settingId

	 */

	function widgetIdToSettingId( widgetId ) {

		var parsed = parseWidgetId( widgetId ), settingId;