JSDocs improvements for 7.2

[afercia]

See #65939, #65951, #65818.

This ticket is for various issues and improvements to the JavaScript inline documentation surfaced via JSDocs.

JSDocs has been restored to a working configuration in #65939. So far, the configuration is a minimal one and only checks for a few rules. The plan is to progressively extend the rules in the configuration ans fix the newly reported issues.

This task originates from ​the ​JavaScript Inline Docs Initiative which is a much needed long-term project. The effort started in the initiative has somehow stalled across the years. Now, JSDocs provides a convenient tool to revive the initiative and complete the task.

Suggested workflow for anyone willing to contribute to this effort:

Recommended rules to start with, in this order:

1. jsdoc/require-description
2. jsdoc/require-returns
3. jsdoc/require-returns-type
4. jsdoc/require-returns-description
5. jsdoc/require-jsdoc

• Temporarily add 'jsdoc/require-description': 'error', to ​the configuration.
• Fix the issues, in this case by adding the reported missing descriptions.
• Avoid to submit a patch / PR that touches too many files at the same time. Prefer splitting into separate patches / PRs with a reasonable size, at your judgment.
• Verify there are no pending patches / PRs that already fix those files.
• Do not commit the added rule in the configuration.
• Once all the reported issues are fixed, the new rule can be added and committed.
• Repeat the cycle with a new rule.

Cc @westonruter

[westonruter]

In 63454:

Customize: Document and modernize the JS base API.

The variadic signatures could not be documented without names for their arguments, so the arguments object is replaced with modern rest parameters across wp.customize.Class, Events, Value, Values, Element and Messenger. The Array.prototype.slice alias they relied on is no longer needed and is removed. Rest parameters are supported by >96% of users globally and all browser versions supported by WordPress.

The argument these two files receive was named exports, while the docblock beside the line using it said window.wp.customize. It is now wp, and the arguments of both wrapping functions are documented.

Many of the types named nothing that resolves. Seven tags were typed mixed, which is not a JSDoc type; one still carried the [type] placeholder an IDE had left behind; and one each read ..., an unqualified Value, and string|jQuery collection, which is two words rather than a type expression. Where the jQuery namespace appeared it was spelled in lower case, so it named the $ function rather than a collection or an event. The value accepted by Value#set() was typed as an object, though a Value holds anything. In loader.js the one documented parameter had no braces at all.

The remaining docblocks are new, since most of these methods carried none. Among what they now record: Class returns a function rather than an object whenever the prototype defines an instance method, which is how wp.customize() and wp.customize.control() come to be callable, and Value#link() binds the receiver to follow the values it is given rather than the reverse.

QUnit tests cover the applicator form of the constructor, the forwarding of arguments through the event methods, and unsync() in both directions, resolving two long-standing todos in that file.

Developed as subset of ​https://github.com/WordPress/wordpress-develop/pull/10743.
Follow-up to r48110, r48650.

Props westonruter, afercia, grapplerulrich, vishalkakadiya, shailu25.
See #39671, #40831, #64662, #66033.

[westonruter]

In 63455:

Customize: Correct the JSDoc for the controls API.

Many of the types named nothing that resolves. The four deferred getters referred to their callback typedefs without a namespace, the promise they return was spelled jQuery.promise, which is neither the capitalization the namespace is declared under nor the name of a type, and jQuery events were typed as plain objects.

Two blocks documented the wrong thing outright. ThemesPanel lent its prototype to a name misspelled without the second e, so its methods were attached to a namespace that exists nowhere else, and getInitialHeaderImage() carried the return of the method beside it, describing a set of cropper options where its own summary already said it returns a model.

Parameters the code treats as optional are marked as such.

Developed as subset of ​https://github.com/WordPress/wordpress-develop/pull/10743.
Follow-up to r41799, r48650, r63454.

Props westonruter, afercia.
See #39671, #39930, #40831, #64662, #66033.

[westonruter]

In 63456:

Customize: Correct the widgets and menus JSDoc.

Three blocks described something the code does not do.

1. WidgetsPanel lent its prototype to WigetsPanel, so its methods were attached to a name that appears nowhere else in core.
2. WidgetControl.onChangeExpanded() said its arguments were merged over defaultActiveArguments, while the handler that calls it merges over defaultExpandedArguments; the two carry separate defaults and separate queues, so the wrong one points a reader at the wrong callback.
3. The field toggle handler in the menu section annotated this as a jQuery object, when it is used with each() and a click binding, both of which set this to the raw element its body then wraps.

The offset parameters described what they accept by writing out the two literals it may hold, which does not convey that the sign selects a direction rather than an amount.

Developed as subset of ​https://github.com/WordPress/wordpress-develop/pull/10743.
Follow-up to r48650, r63454, r63455.

Props westonruter, afercia.
See #39671, #40831, #64662, #66033.

[westonruter]

In 63457:

Customize: Correct the JSDoc in the preview frame.

Missing tags and descriptions are added, and the types are corrected, whether they named nothing resolvable (Promise for JQuery.Promise<*>), said too little (Array for string[]), or were narrower than what the code passes.

Both classes in selective-refresh.js lent their prototypes to the wrong name: Partial named wp.customize.SelectiveRefresh.Partial, capitalized unlike the namespace it lives in, and Placement named wp.customize.selectiveRefresh itself, so its methods were attached to the module rather than to the class.

Developed as subset of ​https://github.com/WordPress/wordpress-develop/pull/10743.
Follow-up to r48110, r48650, r63454, r63455, r63456.

Props westonruter, afercia, grapplerulrich, mukesh27.
See #39671, #40831, #64662, #66033.

[westonruter]

In 63458:

Customize: Document the header image models and views.

Neither file documented a single method: only the classes themselves carried a docblock. Every method across the two now says what it does, in the third person, along with the arguments of the function wrapping each file.

One behavior is changed: ChoiceListView.render() returned nothing, unlike the sibling views beside it, so it now returns this as the Backbone convention expects. Nothing reads the value, since the view is only ever constructed, never chained, and render is otherwise reached as a listenTo handler, whose return is discarded.

Developed as subset of ​https://github.com/WordPress/wordpress-develop/pull/10743.
Follow-up to r63454, r63455, r63456, r63457.

Props westonruter, afercia, grapplerulrich.
See #39671, #64662, #66033.
Fixes #40831.

[afercia]

In 63464:

Build/Test Tools: Integrate lint:jsdoc into the Core development workflow.

This changeset adds a lint:jsdoc Grunt task and includes it in the precommit:js task list.

The existing lint:jsdoc NPM script was restored to a working configuration in #65939. It broke with the upgrade of ESLint to version 10 in the @wordpress/scripts package in the Gutenberg repository. See ​https://github.com/WordPress/gutenberg/pull/76654.

By including lint:jsdoc into CI, future potential breakages will be detected soon. Also, this change aims to reinforce the long-term goal of improving the JavaScript inline documentation that was started years ago in the ​WordPress JavaScript Docs Coding Standards initiative. See ​https://make.wordpress.org/core/handbook/docs/inline/js/.
Future improvements will be part of ongoing maintenance work. See for example #66033.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/13336

Props afercia, westonruter.
See #65939, #65950, #66033.

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

In preparation of the introduction of the rule jsdoc/require-description for JSDoc, this PR adds several missing descriptions to JS functions in the enqueues directory. Leaves out:

• All the Customize related files.
• All the Media related files.

## Use of AI Tools

AI assistance: Yes
Tool(s): GitHub Copilot
Model(s): Claude Haiku 4.5
Used for: Quickly drafting some descriptions.

[afercia]

In 63514:

General: Add missing descriptions to several JS docblocks in the enqueues directory.

Part of the effort to improve JS inline documentation for WordPress 7.2. Preparation for the introduction of the JSDoc rule jsdoc/require-description.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/13421

See #66033.

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

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

In preparation of the introduction of the rule jsdoc/require-description for JSDoc, this PR adds several missing descriptions to JS functions in the media directory.

## Use of AI Tools

AI assistance: Yes
Tool(s): GitHub Copilot
Model(s): Claude Haiku 4.5
Used for: Quickly drafting some descriptions.

[afercia]

In 63516:

General: Add missing descriptions to several JS docblocks in the media directory.

Part of the effort to improve JS inline documentation for 7.2. Preparation for the introduction of the JSDoc rule jsdoc/require-description.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/13423

See #66033.

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

In preparation of the introduction of the rule jsdoc/require-description for JSDoc, this PR adds several missing descriptions to the Customize JS functions.

Also, enables the jsdoc/require-description JSDoc rule.

• Run npm run lint:jsdoc and observe there are no reported errors.
• Check the added descriptions are meaningful.

## Use of AI Tools

AI assistance: Yes
Tool(s): GitHub Copilot
Model(s): Claude Haiku 4.5
Used for: Quickly drafting some descriptions.

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

See also the post-commit suggestions I l just left in ​https://github.com/WordPress/wordpress-develop/pull/13423

Minor JSDocs fixes after CR on ​https://github.com/WordPress/wordpress-develop/pull/13423

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

## Use of AI Tools

None

[afercia]

In 63521:

General: Minor JSDoc fixes after r63516.

Part of the effort to improve JS inline documentation for 7.2.
Amends [63516]

Developed in ​https://github.com/WordPress/wordpress-develop/pull/13426

Props westonruter, afercia.
See #66033.

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

[afercia]

In 63525:

General: Add missing descriptions to the Customize JavaScript docs.

Part of the effort to improve JS inline documentation for 7.2. Preparation for the introduction of the JSDoc rule jsdoc/require-description.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/13424

Props afercia, westonruter.
See #66033.

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

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

• Enables the jsdoc/require-jsdoc JSDoc rule.
• Fixes all the reported 73 violations of missing docblocks.

Run npm run lint:jsdoc and observe there are no reported violations.

To evaluate for the future:
​https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-jsdoc.md#require

By default, the jsdoc/require-jsdoc options > require setting enables this check only for FunctionDeclaration.
When enabling all the other options (see below) ~900 additional violations are reported:

'jsdoc/require-jsdoc': [ 'error', {
	require: {
		FunctionDeclaration: true,
		ArrowFunctionExpression: true, // false by default
		ClassDeclaration: true,        // false by default
		ClassExpression: true,         // false by default
		FunctionExpression: true,      // false by default
		MethodDefinition: true,        // false by default
	},
} ],

## Use of AI Tools

AI assistance: Yes
Tool(s): GitHub Copilot
Model(s): Claude Haiku 4.5
Used for: Quickly drafting some descriptions.

[westonruter]

In 63545:

Administration: Wrap more one-liner inline scripts.

Continuing the migration begun in r63481, the raw one-liner SCRIPT tags in wp-admin/admin-footer.php, wp-admin/install.php and wp-admin/async-upload.php now print through wp_print_inline_script_tag(), so wp_inline_script_attributes can attach a per-request nonce to these as well.

The upload error handler is reworked in the process:

1. Its data now crosses into JavaScript as a single wp_json_encode() object rather than being interpolated into the script text, which also removes the raw interpolation of the dismiss button's generated id.
2. The jQuery object arrives as an argument instead of being read from the global scope four times.
3. setTimeout() replaces the lone _.delay() call, which was all the snippet wanted from Underscore.

The two blocks that take an argument carry a JSDoc block naming its type, following the convention already used for the jQuery wrapper in wp-admin/js. These particular blocks are not reached by lint:jsdoc, which reads JavaScript files rather than heredocs embedded in PHP, but IDEs do check them.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/13393.
Follow-up to r60263, r60520, r60681, r63481.

Props thanhtinpk, westonruter.
See #59446, #66033.

[afercia]

In 63556:

General: Add missing JS docblocks.

Also, enables the JSDoc rule jsdoc/require-jsdoc.
Part of the effort to improve JS inline documentation for 7.2.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/13439

Props afercia, westonruter.
See #66033.

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

[afercia]

Next JSDoc rules worth considering to be added:

Functional:

'jsdoc/require-param-description': 'error',
'jsdoc/require-param-name': 'error',
'jsdoc/valid-types': 'error',

Indentation / alignments / formatting:

'jsdoc/require-hyphen-before-param-description': [ 'error', 'never' ],
'jsdoc/check-alignment': 'error',
'jsdoc/check-indentation': 'error',
'jsdoc/check-line-alignment': [ 'error', 'always', {
	tags: [ 'param', 'arg', 'argument', 'property', 'prop', 'template' ],
} ],

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

• Enables the jsdoc/require-param-name JSDoc rule.
• Sorts rules alphabetically.

## Use of AI Tools

[afercia]

In 63577:

General: Enable the JSDoc rule require-param-name.

Also, sorts the rules alphabetically in .eslintrc-jsdoc.js.
Part of the effort to improve JS inline documentation for 7.2.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/13473

See #66033.

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

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

• Enables the JSDoc rule require-param-description.
• Fixes all the reported violations.

Run npm run lint:jsdoc and observe there are no reported violations.

## Use of AI Tools

[afercia]

In 63598:

General: Enable the JSDoc rule require-param-description.

Enables the JSDoc rule require-param-description and fixes all the reported violations.
Part of the effort to improve JS inline documentation for 7.2.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/13475

Props afercia, westonruter.
See #66033.

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

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

• Enables the JSDoc rule jsdoc/valid-types.
• Todo: Fixes 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

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

• Enables the following JSDoc rules:
  • jsdoc/check-alignment
  • jsdoc/check-indentation
  • jsdoc/check-line-alignment
  • jsdoc/require-hyphen-before-param-description -> never
• Fixes all the violations.

This is a purely formatting fix.

## Use of AI Tools

[afercia]

I'm wondering whether the docblocks of the JS files within ​the tools directory should be linted as well.

[afercia]

In 63600:

General: Fix indentation and alignments in JavaScript inline documentation blocks.

Enables the following JSDoc rules:

• jsdoc/check-alignment
• jsdoc/check-indentation
• jsdoc/check-line-alignment
• jsdoc/require-hyphen-before-param-description -> never

Fixes all the reported violations. Also removes hyphens before descriptions.

Part of the effort to improve JS inline documentation for 7.2.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/13490

Props afercia, mukesh27.
See #66033.

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

[afercia]

In 63766:

General: Enable the JSDoc rule valid-types.

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 ​https://github.com/WordPress/wordpress-develop/pull/13486

See #66033.

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

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

Enables the following JSDoc rules:

• jsdoc/check-property-names
• jsdoc/require-property
• jsdoc/require-property-name
• jsdoc/require-property-description
• jsdoc/require-property-type

Fixes all the related violations.

Use of AI Tools

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

Enables the following JSDoc rules:

• jsdoc/no-blank-blocks
• jsdoc/no-blank-block-descriptions

No current violations to fix.

Use of AI Tools

[afercia]

In 63769:

General: Enable the JSDoc no blank blocks and descriptions rules.

Enables the following JSDoc rules:

• jsdoc/no-blank-blocks
• jsdoc/no-blank-block-descriptions

Part of the effort to improve JS inline documentation for 7.2.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/13634

See #66033.

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

[afercia]

In 63775:

General: Enable the JSDoc rules related to the property tag.

Enables the following JSDoc rules:

• jsdoc/check-property-names
• jsdoc/require-property
• jsdoc/require-property-name
• jsdoc/require-property-description
• jsdoc/require-property-type

Fixes all the related violations.
Part of the effort to improve JS inline documentation for 7.2.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/13632

See #66033.

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

[afercia]

Overall, the work done so far has greatly improved the JavaScript inline documentation. Most importantly, there is now a working tool integrated in the CI that checks for the documentation coding standards.

Also, any modern IDE can take advantage by the updated JSDoc config as the IDE autocomplete will understand how to suggest meaningful docblocks. Not to mention that indentation and alignments will be fixed automatically when saving.

Next steps I'd recommend:

1
Upgrade the eslint-plugin-jsdoc version to latest. This is strongly recommended as the new version will likely report new violations that should be fixed before any other change. The related issue in the Gutenberg repository should be prioritized. See ​https://github.com/WordPress/gutenberg/issues/82726

2
After that, start expanding some of the most important rules. For example ​the require-jsdoc rule has a require option that defaults to true only for FunctionDeclaration. Expanding true to the following should be considered soon:

• ArrowFunctionExpression
• ClassDeclaration
• ClassExpression
• FunctionExpression
• MethodDefinition

Follow-up to ​https://github.com/WordPress/wordpress-develop/pull/13486

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

Use of AI Tools

[afercia]

In 63791:

General: Better documentation for the sync functions in the wp api.js file.

Amends [63766]. Better document the options param and return tag for the sync functions in src/js/_enqueues/wp/api.js.

Part of the effort to improve JS inline documentation for 7.2.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/13650

Props westonruter, afercia.
See #66033.

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