1950163 - Disable ESLint rule jsdoc/require-param-description, enable jsdoc/require-param-type

Status: RESOLVED FIXED

(Developer Infrastructure :: Lint and Formatting, task, P3)

Description

[Mark Banner (:standard8)]

After a discussion, we have agreed that the jsdoc/require-param-description rule can cause unnecessary documentation for things like:

  /**
   * Attempts to determine the language in which the document's content is written.
   *
   * @param {Document} document
   * @returns {string | null}
   */

Where it is obvious as to what document is. Although we would like to encourage parameter descriptions wherever reasonable, we decided it would be difficult to design a rule/requirement that is based on the rule type - as there would still be some situations where it becomes difficult.

We have also agreed to enable the jsdoc/require-param-type rule as that is useful, especially with switching to TypeScript and currently gives no errors for the places where the require-jsdoc configuration is already enabled.

Comment 1

[Mark Banner (:standard8)]

Attachment: Bug 1950163 - Disable ESLint rule jsdoc/require-param-description, enable jsdoc/require-param-type. r?#frontend-codestyle-reviewers!

Comment 2

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/integration/autoland/rev/ec6c742b5115
Disable ESLint rule jsdoc/require-param-description, enable jsdoc/require-param-type. r=frontend-codestyle-reviewers,Gijs

Comment 3

[Serban Stanca [:SerbanS]]

https://hg.mozilla.org/mozilla-central/rev/ec6c742b5115

Comment 4

[Greg Tatum [:gregtatum]]

Thanks Mark for this tweak! I appreciate the time taken to consider the change and implementing it.