Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

jsdoc/no-undefined-types should not warn when Prefix~ is omitted #590

Open
NovemLinguae opened this issue Jun 30, 2024 · 1 comment
Open

Comments

@NovemLinguae
Copy link

NovemLinguae commented Jun 30, 2024

Example:

	/**
	 * @typedef {Object} mw.widgets.NamespaceInputWidget~DropdownOptions
	 * @property {any} data
	 * @property {string} label
	 */

	/**
	 * Get a list of namespace options, sorted by ID.
	 *
	 * @method getNamespaceDropdownOptions
	 * @param {Object} [config] Configuration options
	 * @return {DropdownOptions[]} Dropdown options
	 * @memberof mw.widgets.NamespaceInputWidget
	 */
	mw.widgets.NamespaceInputWidget.static.getNamespaceDropdownOptions = function ( config ) {

The line @return {DropdownOptions[]} Dropdown options warns with The type 'DropdownOptions' is undefined.eslintjsdoc/no-undefined-types

The eslint warning can be fixed by changing this to @return {mw.widgets.NamespaceInputWidget~DropdownOptions[]} Dropdown options, but this has downsides:

  • breaks VS Code tooltips
    image
  • makes generated docs (npm run doc) more verbose (and worked fine the old way)
    image
  • makes docblock more verbose

When running npm run doc, omitting Prefix~ even works across files. Example: FieldSpecificationObject.

Per this code review discussion, it might make more sense to fix this in eslint-config-wikimedia. Thoughts?

@NovemLinguae
Copy link
Author

Giving a @link without specifying the Prefix~ gives the same problem as above. npm run doc handles it fine, but eslint wants the Prefix~ added. Perhaps we should fix that as well. Example:

/**
 * Exposes an instance of {@link AuthPopup} configured to display a login dialog for the local
 * instance of MediaWiki.
 *
 * The promises returned by `AuthPopup` methods will be resolved with a {@link userinfo} object.

The last line generates an eslint warning, but is fine in the generated documentation.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Development

No branches or pull requests

1 participant