Lint all JSDocs. - #13251
Closed
afercia wants to merge 16 commits into
Closed
Conversation
|
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 Core Committers: Use this line as a base for the props when committing in SVN: To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
Test using WordPress PlaygroundThe 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
For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation. |
afercia
force-pushed
the
lint-all-jsdocs
branch
from
August 25, 2026 06:51
eb9cc48 to
fe222a0
Compare
westonruter
requested changes
Aug 25, 2026
Comment on lines
-176
to
+174
| function configureLinting( settings ) { // eslint-disable-line complexity | ||
| function configureLinting( settings ) { |
Member
Author
There was a problem hiding this comment.
Why? In Core there is no ESLint rule so far that checks for complexity. This comment is unnecessary.
Comment on lines
-201
to
+199
| function getLintOptions() { // eslint-disable-line complexity | ||
| function getLintOptions() { |
afercia
force-pushed
the
lint-all-jsdocs
branch
from
August 25, 2026 21:27
d39bba5 to
c1ccc41
Compare
westonruter
requested changes
Aug 25, 2026
westonruter
left a comment
westonruter
left a comment
Member
There was a problem hiding this comment.
I didn't add review comments for every single requested change. You get the idea.
(This may be too large a scope to do in one commit.)
afercia
commented
Aug 26, 2026
afercia
commented
Aug 26, 2026
afercia
commented
Aug 26, 2026
afercia
commented
Aug 26, 2026
afercia
commented
Aug 26, 2026
afercia
commented
Aug 26, 2026
afercia
commented
Aug 26, 2026
afercia
commented
Aug 26, 2026
afercia
commented
Aug 26, 2026
afercia
commented
Aug 26, 2026
afercia
commented
Aug 26, 2026
afercia
commented
Aug 26, 2026
afercia
commented
Aug 26, 2026
afercia
force-pushed
the
lint-all-jsdocs
branch
from
August 26, 2026 08:14
c1ccc41 to
efdc17f
Compare
Member
Author
|
Regarding the optional hyphen before the param description, it can be disallowed or required via the jsdoc/require-hyphen-before-param-description rule. However, as mentioned in the review comments, making it required would need a proposal to change the JS docs coding standards. |
Member
Author
|
The missing param types were not flagged because of a typo in the new configuration I'm using to lint the files, where jsdoc/require-param-type was duplicated and ultimately set to 'off'. |
afercia
force-pushed
the
lint-all-jsdocs
branch
from
August 28, 2026 13:26
88863a5 to
80ef5f1
Compare
Member
Author
|
Now thaat the new JSDoc configuration has been merged in core, I rebased this PR on top of trunk. Running:
should now report no errors. |
westonruter
reviewed
Aug 28, 2026
| * | ||
| * @since 6.4.0 | ||
| * | ||
| * @return {Object} Public methods. |
Member
There was a problem hiding this comment.
Interesting, as the returned object is not assigned to anything.
Member
|
Per #13251 (comment), I'll adopt all of the Customizer changes to work on separately for Core-40831 to merge with #10743. |
afercia
commented
Aug 28, 2026
| */ | ||
|
|
||
| /* global _wpCustomizeHeader, _wpCustomizeBackground, _wpMediaViewsL10n, MediaElementPlayer, console, confirm */ | ||
| (function( exports, $ ){ |
Member
Author
There was a problem hiding this comment.
I think this exports is a typo and should be wp
Member
Member
westonruter
approved these changes
Aug 31, 2026
westonruter
left a comment
westonruter
left a comment
Member
There was a problem hiding this comment.
LGTM! (Some trailing minor suggestions.)
| /** | ||
| * Triggers the primary submit when then secondary submit is clicked. | ||
| * | ||
| * @param {Event} e The event object. |
Member
There was a problem hiding this comment.
Suggested change
| * @param {Event} e The event object. | |
| * @param {SubmitEvent} e The event object. |
| * Helper for capitalizing strings. | ||
| * | ||
| * @param {string} str The string to capitalize. | ||
| * |
Comment on lines
+1019
to
+1021
| * @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. |
Member
There was a problem hiding this comment.
Suggested change
| * @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 {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. |
Comment on lines
+859
to
+861
| * @param {string} method The CRUD method ("create", "read", "update", or "delete") to be performed. | ||
| * @param {Backbone.Model} model The model to be synced. | ||
| * @param {{beforeSend}, *} options Additional options for the sync. |
Member
There was a problem hiding this comment.
Suggested change
| * @param {string} method The CRUD method ("create", "read", "update", or "delete") to be performed. | |
| * @param {Backbone.Model} model The model to be synced. | |
| * @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 {{beforeSend}, *} options Additional options for the sync. |
There was a problem hiding this comment.
Pull request overview
This PR updates JSDoc blocks across WordPress’ JavaScript sources (media, admin, and shared libraries) to satisfy stricter lint:jsdoc requirements and improve type/return annotations, as part of Trac #65951 (and dependent on #13237’s lint config changes).
Changes:
- Standardize JSDoc primitive/object type casing and add missing
@param/@returndescriptions. - Clarify return types (including “void-or-value” patterns) and improve short method summaries for lint compliance.
- Clean up a few legacy/invalid JSDoc tags and related comment formatting.
Reviewed changes
Copilot reviewed 94 out of 94 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| src/js/media/views/uploader/window.js | JSDoc type casing updates for options. |
| src/js/media/views/uploader/status.js | Adds method summaries / return docs; adjusts parent-call comment style. |
| src/js/media/views/uploader/inline.js | Adds method summaries / return docs; adjusts parent-call comment style. |
| src/js/media/views/uploader/editor.js | Adds return docs and clearer boolean return description. |
| src/js/media/views/toolbar.js | Adds method summary and return description. |
| src/js/media/views/priority-list.js | Adds summaries and return descriptions for list helpers. |
| src/js/media/views/modal.js | Adds method summaries and improves param/return docs. |
| src/js/media/views/menu.js | Adds return description to toView(). |
| src/js/media/views/media-details.js | Adds return description. |
| src/js/media/views/frame/manage.js | Documents event/model parameters. |
| src/js/media/views/frame/edit-attachments.js | Documents rerender/key event params. |
| src/js/media/views/frame.js | Fixes param typing and clarifies boolean/void returns. |
| src/js/media/views/focus-manager.js | Removes incorrect/unused param docs. |
| src/js/media/views/embed/url.js | Adds render summary and clarifies void-or-chain return. |
| src/js/media/views/button-group.js | Adds render summary and return description. |
| src/js/media/views/attachments/browser.js | JSDoc type casing updates for options. |
| src/js/media/views/attachment/details.js | Removes incorrect/unused param docs. |
| src/js/media/views/attachment.js | Adds method summaries, fixes placeholder types, clarifies returns. |
| src/js/media/views/attachment-compat.js | Clarifies void-or-chain return type. |
| src/js/media/models/selection.js | Adds return descriptions for selection helpers. |
| src/js/media/models/query.js | Improves constructor param types and promise return descriptions; fixes tag usage. |
| src/js/media/models/post-image.js | Fixes numeric types for attributes. |
| src/js/media/models/attachments.js | Improves constructor/options docs and multiple return descriptions. |
| src/js/media/models/attachment.js | Clarifies sync/saveCompat return docs and factory return description. |
| src/js/media/controllers/state.js | Documents view parameter. |
| src/js/media/controllers/state-machine.js | Clarifies void-or-state return type. |
| src/js/media/controllers/replace-image.js | JSDoc type casing updates; fixes numeric types; documents initialize options. |
| src/js/media/controllers/region.js | JSDoc type casing updates and return description. |
| src/js/media/controllers/media-library.js | Documents initialize options. |
| src/js/media/controllers/library.js | JSDoc type casing updates; improves multiple return descriptions. |
| src/js/media/controllers/image-details.js | JSDoc type casing updates; fixes numeric types; documents initialize options. |
| src/js/media/controllers/featured-image.js | JSDoc type casing updates; fixes numeric types. |
| src/js/media/controllers/embed.js | JSDoc type casing updates; fixes numeric types; updates metadata type casing. |
| src/js/media/controllers/edit-image.js | JSDoc type casing updates. |
| src/js/media/controllers/cropper.js | Documents attachment param. |
| src/js/media/controllers/collection-edit.js | JSDoc type casing updates; fixes numeric types; names a param. |
| src/js/media/controllers/collection-add.js | JSDoc type casing updates; fixes numeric types. |
| src/js/_enqueues/wp/widgets/text.js | Adds IIFE param typing for jQuery. |
| src/js/_enqueues/wp/widgets/media.js | Adds IIFE param typing for jQuery. |
| src/js/_enqueues/wp/widgets/media-image.js | Fixes @type casing. |
| src/js/_enqueues/wp/widgets/media-gallery.js | Fixes @type casing. |
| src/js/_enqueues/wp/widgets/custom-html.js | Adds IIFE param typing for jQuery. |
| src/js/_enqueues/wp/util.js | Fixes Function casing; modernizes optional param syntax. |
| src/js/_enqueues/wp/updates.js | Large-scale JSDoc normalization (types, optional params, return docs). |
| src/js/_enqueues/wp/theme.js | Replaces @uses with actual param docs where appropriate. |
| src/js/_enqueues/wp/theme-plugin-editor.js | Adds IIFE param docs; modernizes/normalizes JSDoc tags; removes legacy ignore blocks. |
| src/js/_enqueues/wp/sanitize.js | Removes outdated eslint-env comment. |
| src/js/_enqueues/wp/revisions.js | JSDoc type casing updates. |
| src/js/_enqueues/wp/media/views.js | Adds return description. |
| src/js/_enqueues/wp/media/models.js | Clarifies void-or-frame return; adds return descriptions. |
| src/js/_enqueues/wp/media/editor.js | Adds/clarifies return descriptions and void returns. |
| src/js/_enqueues/wp/media/audiovideo.js | Documents param and return. |
| src/js/_enqueues/wp/mce-view.js | Normalizes union types, boolean casing, adds param docs. |
| src/js/_enqueues/wp/heartbeat.js | Adds IIFE param docs; normalizes class tag usage; adds param docs. |
| src/js/_enqueues/wp/emoji.js | Adds top-level param docs. |
| src/js/_enqueues/wp/embed.js | Adds top-level param docs; improves message event param docs; updates iframe variable doc. |
| src/js/_enqueues/wp/editor/dfw.js | Adds IIFE param docs; normalizes Function/Object casing; clarifies params. |
| src/js/_enqueues/wp/editor/base.js | Adds return docs and clarifies void-or-value return types. |
| src/js/_enqueues/wp/dashboard.js | Improves param and return typing for community events helpers; fixes @type casing. |
| src/js/_enqueues/wp/custom-header.js | Improves boolean return descriptions and handler constructor doc typing. |
| src/js/_enqueues/wp/code-editor.js | Normalizes typedef object casing; removes inline eslint complexity disables. |
| src/js/_enqueues/wp/autosave.js | Adds IIFE param docs for jQuery/window; adds param docs for storage helper. |
| src/js/_enqueues/wp/api.js | Adds top-level param docs and multiple missing param/return docs. |
| src/js/_enqueues/wp/api-request.js | Adds IIFE param typing for jQuery. |
| src/js/_enqueues/lib/quicktags.js | Normalizes param types, optional params, and return typing for back-compat APIs. |
| src/js/_enqueues/lib/pointer.js | Adds IIFE param typing; clarifies promise-or-void return. |
| src/js/_enqueues/lib/nav-menu.js | Adds IIFE param typing; normalizes types; whitespace cleanup. |
| src/js/_enqueues/lib/lists.js | Adds IIFE param typing; normalizes callback param object types. |
| src/js/_enqueues/lib/list-revisions.js | Adds top-level param docs. |
| src/js/_enqueues/lib/image-edit.js | Moves globals header; adds IIFE param docs; adds multiple missing param/return docs. |
| src/js/_enqueues/lib/emoji-loader.js | Normalizes object typedef casing and return docs; removes outdated eslint-env. |
| src/js/_enqueues/lib/cookies.js | Adds missing param/return docs for cookie helpers. |
| src/js/_enqueues/lib/comment-reply.js | Clarifies return type and multiple param/return docs. |
| src/js/_enqueues/lib/color-picker.js | Adds IIFE param docs; normalizes param typing and return docs. |
| src/js/_enqueues/lib/codemirror/javascript-lint.js | Normalizes typedef formatting and uses @return consistently. |
| src/js/_enqueues/lib/auth-check.js | Adds IIFE param typing for jQuery. |
| src/js/_enqueues/lib/admin-bar.js | Clarifies boolean-or-void return; adds missing return docs. |
| src/js/_enqueues/lib/accordion.js | Adds IIFE param typing for jQuery. |
| src/js/_enqueues/admin/widgets.js | Normalizes JSDoc member tags/types for widget admin globals. |
| src/js/_enqueues/admin/user-profile.js | Moves globals header; adds IIFE param typing; normalizes boolean casing and param name. |
| src/js/_enqueues/admin/tags.js | Adds jQuery IIFE param doc. |
| src/js/_enqueues/admin/tags-suggest.js | Adds jQuery IIFE param doc. |
| src/js/_enqueues/admin/site-icon.js | Fixes attributes param type. |
| src/js/_enqueues/admin/site-health.js | Improves param/return docs for helpers. |
| src/js/_enqueues/admin/post.js | Adds multiple IIFE param docs and improves helper docblocks. |
| src/js/_enqueues/admin/inline-edit-tax.js | Adds IIFE param docs and normalizes namespace doc. |
| src/js/_enqueues/admin/inline-edit-post.js | Adds IIFE param docs and clarifies bulk return behavior. |
| src/js/_enqueues/admin/edit-comments.js | Moves globals header; adds IIFE param doc. |
| src/js/_enqueues/admin/custom-header.js | Adds jQuery IIFE param doc. |
| src/js/_enqueues/admin/custom-background.js | Adds jQuery IIFE param doc. |
| src/js/_enqueues/admin/common.js | Normalizes IIFE param types and return docs; adds missing param docs. |
| src/js/_enqueues/admin/comment.js | Normalizes jQuery param type. |
| src/js/_enqueues/admin/application-passwords.js | Adds jQuery IIFE param doc; normalizes @return. |
| Gruntfile.js | Removes outdated eslint-env comment. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+16
to
18
| * @param {JQueryStatic} $ The jQuery object. | ||
| * @param {Object} window The window object. | ||
| * |
Comment on lines
2328
to
2332
| * @param {(Object|string)} response Response from the server. | ||
| * @param {function=} response.always Optional. Callback for when the Deferred is resolved or rejected. | ||
| * @param {string=} response.statusText Optional. Status message corresponding to the status code. | ||
| * @param {string=} response.responseText Optional. Request response as text. | ||
| * @param {Function} response.always Optional. Callback for when the Deferred is resolved or rejected. | ||
| * @param {string} response.statusText Optional. Status message corresponding to the status code. | ||
| * @param {string} response.responseText Optional. Request response as text. | ||
| * @param {string} action Type of action the response is referring to. Can be 'delete', |
Comment on lines
94
to
96
| for ( i = 0; i < iframes.length; i++ ) { | ||
| /** @var {IframeElement} */ | ||
| /** @member {IframeElement} */ | ||
| source = iframes[ i ]; |
| * | ||
| * This is done by setting it to an empty value and setting the expiration time in the past. | ||
| * | ||
| * @param {string} name The name of th e cookie. |
| * @this Backbone.Model | ||
| * | ||
| * @return {Promise} | ||
| * @return {Promise} A jQuery Promise that is resolved or rejected based on the success of the sync operation. |
Comment on lines
12
to
16
| * A closed Sidebar that gets a Widget dragged over it. | ||
| * | ||
| * @var {element|null} | ||
| * @member {element|null} | ||
| */ | ||
| hoveredSidebar: null, |
Member
Author
@westonruter thank you. |
afercia
force-pushed
the
lint-all-jsdocs
branch
from
August 31, 2026 09:38
97b90e2 to
6759bae
Compare
This was referenced Aug 31, 2026
Closed
Member
Author
|
Note that, in preparation of the SVN commit to bring in this change, I split this pull request into 4 smaller ones (listed above). I will commit them separately to not touch a large amount of files at the same time. Fixes for the Customizer files have been split to #10743 |
afercia
added
the
props-bot
github-actions
Bot
removed
the
props-bot
pento
pushed a commit
that referenced
this pull request
Aug 31, 2026
Fixes the JSDoc violations reported by the `lint:jsdoc` updated configuraiton after [63392]. First part, Developed in #13251 Props afercia, westonruter. See #65951, #65939. git-svn-id: https://develop.svn.wordpress.org/trunk@63406 602fd350-edb4-49c9-b593-d223f7449a82
markjaquith
pushed a commit
to markjaquith/WordPress
that referenced
this pull request
Aug 31, 2026
Fixes the JSDoc violations reported by the `lint:jsdoc` updated configuraiton after [63392]. First part, Developed in WordPress/wordpress-develop#13251 Props afercia, westonruter. See #65951, #65939. Built from https://develop.svn.wordpress.org/trunk@63406 git-svn-id: http://core.svn.wordpress.org/trunk@62599 1a063a9b-81f0-0310-95a4-ce76da25c4cd
pento
pushed a commit
that referenced
this pull request
Aug 31, 2026
Fixes the JSDoc violations reported by the `lint:jsdoc` updated configuraiton after [63392]. Second part, Developed in #13251 Props afercia, westonruter. See #65951, #65939. git-svn-id: https://develop.svn.wordpress.org/trunk@63407 602fd350-edb4-49c9-b593-d223f7449a82
markjaquith
pushed a commit
to markjaquith/WordPress
that referenced
this pull request
Aug 31, 2026
Fixes the JSDoc violations reported by the `lint:jsdoc` updated configuraiton after [63392]. Second part, Developed in WordPress/wordpress-develop#13251 Props afercia, westonruter. See #65951, #65939. Built from https://develop.svn.wordpress.org/trunk@63407 git-svn-id: http://core.svn.wordpress.org/trunk@62600 1a063a9b-81f0-0310-95a4-ce76da25c4cd
pento
pushed a commit
that referenced
this pull request
Aug 31, 2026
Fixes the JSDoc violations reported by the `lint:jsdoc` updated configuraiton after [63392]. Third part, Developed in #13251 Props afercia, westonruter. See #65951, #65939. git-svn-id: https://develop.svn.wordpress.org/trunk@63408 602fd350-edb4-49c9-b593-d223f7449a82
markjaquith
pushed a commit
to markjaquith/WordPress
that referenced
this pull request
Aug 31, 2026
Fixes the JSDoc violations reported by the `lint:jsdoc` updated configuraiton after [63392]. Third part, Developed in WordPress/wordpress-develop#13251 Props afercia, westonruter. See #65951, #65939. Built from https://develop.svn.wordpress.org/trunk@63408 git-svn-id: http://core.svn.wordpress.org/trunk@62601 1a063a9b-81f0-0310-95a4-ce76da25c4cd
pento
pushed a commit
that referenced
this pull request
Aug 31, 2026
Fixes the JSDoc violations reported by the `lint:jsdoc` updated configuraiton after [63392]. Last part, Developed in #13251 Props afercia, westonruter. See #65939. Fixes #65951. git-svn-id: https://develop.svn.wordpress.org/trunk@63409 602fd350-edb4-49c9-b593-d223f7449a82
markjaquith
pushed a commit
to markjaquith/WordPress
that referenced
this pull request
Aug 31, 2026
Fixes the JSDoc violations reported by the `lint:jsdoc` updated configuraiton after [63392]. Last part, Developed in WordPress/wordpress-develop#13251 Props afercia, westonruter. See #65939. Fixes #65951. Built from https://develop.svn.wordpress.org/trunk@63409 git-svn-id: http://core.svn.wordpress.org/trunk@62602 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Trac ticket: https://core.trac.wordpress.org/ticket/65951
Needs #13237 to be merged first.
Use of AI Tools
None
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.