Enable the JSDoc rule `valid-types` by afercia · Pull Request #13486 · WordPress/wordpress-develop

afercia · 2026-09-11T06:39:24Z

See https://core.trac.wordpress.org/ticket/66033

Enables the JSDoc rule jsdoc/valid-types.
Todo: Fix all the reported violations.

There are 69 violations of the valid-types rule. @westonruter since you are the types master, would you like to take care of this fix? Just run npm run lint:jsdoc and fix all the reported violations.

Use of AI Tools

AI assistance: Yes
Tool(s): Local Ollama service with Continue in VSCode
Model(s): qwen3.8:27b-mlx
Used for: Research JSDoc fixes. Final implementation checked by me.

This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.

github-actions · 2026-09-11T06:40:11Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props afercia.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

…ile.

github-actions · 2026-09-20T15:12:28Z

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

All changes will be lost when closing a tab with a Playground instance.
All changes will be lost when refreshing the page.
A fresh instance is created each time the link below is clicked.
Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

Enables the JSDoc rule `valid-types` and fixes all the reported violations. Part of the effort to improve JS inline documentation for 7.2. Developed in #13486 See #66033. git-svn-id: https://develop.svn.wordpress.org/trunk@63766 602fd350-edb4-49c9-b593-d223f7449a82

Enables the JSDoc rule `valid-types` and fixes all the reported violations. Part of the effort to improve JS inline documentation for 7.2. Developed in WordPress/wordpress-develop#13486 See #66033. Built from https://develop.svn.wordpress.org/trunk@63766 git-svn-id: http://core.svn.wordpress.org/trunk@62938 1a063a9b-81f0-0310-95a4-ce76da25c4cd

afercia · 2026-09-21T06:36:11Z

Committed in https://core.trac.wordpress.org/changeset/63766

westonruter

@afercia A post-commit review for you.

westonruter · 2026-09-21T17:10:52Z

- * @param {wpList~confirm}   settings.confirm     Callback that's run before a request is made. Default: null.
- * @param {wpList~addBefore} settings.addBefore   Callback that's run before an item gets added to the list.
- *                                                Default: null.
- * @param {wpList~addAfter}  settings.addAfter    Callback that's run after an item got added to the list.
- *                                                Default: null.
- * @param {wpList~delBefore} settings.delBefore   Callback that's run before an item gets deleted from the list.
- *                                                Default: null.
- * @param {wpList~delAfter}  settings.delAfter    Callback that's run after an item got deleted from the list.
- *                                                Default: null.
- * @param {wpList~dimBefore} settings.dimBefore   Callback that's run before an item gets dim'd. Default: null.
- * @param {wpList~dimAfter}  settings.dimAfter    Callback that's run after an item got dim'd. Default: null.


I'm not familiar with this ~ syntax. It does seem unnecessary regardless. However, with TypeScript we could potentially re-introduce some flavor of that.

JSDoc doesn't validate them. Not sure that ~ syntax is still valid. JSDoc can't understand it anyways. After all these are all callback functions. We will see when you will extend TypeScript to this file.

westonruter · 2026-09-21T17:11:30Z

 	/**
 	 * Adds event that opens the time stamp form if the form is hidden.
 	 *
-	 * @listens $edittimestamp:click


Why did these @listens tags need to be removed? They seem valid: https://jsdoc.app/tags-listens

Same: JSDoc doesn't validate them. It doesn't understand this 'path'. Also, not sure what value these @listens tag may add because the function is self-explanatory.... when I read:
$edittimestamp.on( 'click', ....
I already see what I need to know.
That said, if you can find a way to make JSDoc understand these @listens and not report a violation, I'm all for it.

westonruter · 2026-09-21T17:15:45Z

-			 * @param {{beforeSend}, *} options Additional options for the sync.
+			 * @param {string}         method  The CRUD method ("create", "read", "update", or "delete") to be performed.
+			 * @param {Backbone.Model} model   The model to be synced.
+			 * @param {Object}         options Additional options for the sync.


This is now less-specific than before. It seems like it should have been something like this:

Suggested change

* @param {Object} options Additional options for the sync.

* @param {Object} options Additional options for the sync.

* @param {Function} [options.beforeSend] Callback to run before sending.

* @param {Function} [options.success] Callback executed on a successful request.

* @param {Function} [options.error] Callback executed on a failed request.

I don't see options.success or options.error here, while I do see options.complete. I will add it.

They are documented in Backbone's options: https://backbonejs.org/#Sync

I see and all other jQuery request options
Does that mean we should really document ALL those options? I'd say no, and maybe we should just keep the main options object.

Probably, not, no. Let's just do beforeSend.

westonruter · 2026-09-21T17:16:51Z

 			 * @param {string}         method  The CRUD method ("create", "read", "update", or "delete") to be performed.
 			 * @param {Backbone.Model} model   The model to be synced.
-			 * @param {{success}, *}   options Additional options for the sync.
+			 * @param {Object}         options Additional options for the sync.


Ditto above.

westonruter · 2026-09-21T17:17:58Z

-		/**
-		 * @static
-		 * @type Array
-		 */


Curious why this needs to be removed?

Again, JSDoc doesn't validate this. Also, is it a static? Looks like just a local vari to me.

westonruter · 2026-09-21T17:18:08Z

-		/**
-		 * @static
-		 * @type Array
-		 */


Also curious about this removal.

westonruter · 2026-09-21T17:19:00Z

-	 * @fires wp.media.controller.MediaLibrary#attachment:details:shift-tab
-	 * @fires wp.media.controller.MediaLibrary#attachment:keydown:arrow


Why remove these here but they are kept elsehwere?

Because these ones aren't validated by JSDoc :)

Also, I don't understand the value added by these @fires tags. I can see what the function triggers... .trigger( 'attachment:details:shift-tab', event ); by just looking sat the code.

westonruter · 2026-09-21T17:19:21Z

 	 * handlers to prevent duplicate listeners.
 	 *
-	 * @since 4.0.0
+	 * Listens for the `window:resize` event.


No @listens?

Same as above. JSDoc doesn't understand @listens window:resize and honestly these listens tags are useless.

westonruter · 2026-09-21T17:19:46Z

 	 * in the options.
 	 *
-	 * @since 3.5.0
+	 * Fires `collection:reset`.


Why no @fires?

Same as above.

westonruter · 2026-09-21T17:20:18Z

Why no @fires?

Same as above

afercia force-pushed the jsdoc-valid-types branch from 649d54c to d9ad597 Compare September 20, 2026 13:10

afercia added 20 commits September 20, 2026 17:09

Enable JSDoc valid-types.

bbf4573

Remove non-standard JSDoc liatens.

3a7da74

Fix valid types in inline-edit-tax.js file.

5fc6bde

Fix valid types in user-profile.js file.

c952955

Fix valid types in lists.js file.

043dda7

Fix valid types in wp api.js file.

5ca7201

Fix valid types in wp media editor.js file.

bad3cbe

Remove docblock for local variable in theme.js file.

d978758

Fix valid types in widgets media.js file.

da42376

Fix valid types in media models attachment.js file.

dc86b1f

Fix valid types in media models attachments.js file.

a367980

Remove docblock for local variable in media models query.js file.

9df8a69

Remove invalid fires notations in media models selection.js file.

f8c9155

Remove invalid fires notations in media views attachment details.js f…

550dedd

…ile.

Fix valid types in media views attachments.js file.

5303c3c

Fix valid types in media views frame manage.js file.

30d269c

Fix valid types in media views frame select.js file.

d93c359

Remove invalid event notation in media views frame.js file.

f7cfcde

Remove invalid fires notations in media views media-details.js file.

8c053ec

Fix valid types in media views media-frame.js file.

06b5211

afercia force-pushed the jsdoc-valid-types branch from d9ad597 to 06b5211 Compare September 20, 2026 15:09

afercia added 3 commits September 20, 2026 17:15

Fix wp api.js file.

1201c48

Use prose description instead of changing listens notations meaning.

373de73

Improve wp api.hs more function return notation.

43e5ea5

afercia closed this Sep 21, 2026

afercia deleted the jsdoc-valid-types branch September 21, 2026 06:36

westonruter reviewed Sep 21, 2026

View reviewed changes

afercia mentioned this pull request Sep 22, 2026

Jsdoc r63766 follow-up #13650

Closed

afercia added the props-bot Adding this label triggers the Props Bot workflow for a PR. label Sep 22, 2026

-			 * @param {Object}         options Additional options for the sync.
+			 * @param {Object}         options              Additional options for the sync.
+			 * @param {Function}       [options.beforeSend] Callback to run before sending.
+			 * @param {Function}       [options.success]    Callback executed on a successful request.
+			 * @param {Function}       [options.error]      Callback executed on a failed request.

		* @fires wp.media.controller.MediaLibrary#attachment:details:shift-tab
		* @fires wp.media.controller.MediaLibrary#attachment:keydown:arrow

Conversation

afercia commented Sep 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Use of AI Tools

Uh oh!

github-actions Bot commented Sep 11, 2026

Uh oh!

github-actions Bot commented Sep 20, 2026

Test using WordPress Playground

Some things to be aware of

Uh oh!

afercia commented Sep 21, 2026

Uh oh!

westonruter left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

afercia commented Sep 11, 2026 •

edited

Loading