Do not error on missing JSDoc @returns for function

[Gozala]

In an effort to adding JSDoc comments (ipfs/js-ipfs#3046) I end up running into complications with ESLint that seems to complain wherever there is a JSDoc annotation but no @returns annotation.

While I agree with this in principal it is pretty painful in practice because JS-IPFS uses dependency injection pattern a lot. And this requirement causes same annotations to be defined twice once in the inner function and again in the outer function.

Let's consider following example:

/**
 * @typedef {Object} Config
 * @property {Repo} repo
 *
 * @param {Config} config
 */
module.exports = ({ repo }) => {
  /**
   * If the repo has been initialized, report the current version.
   * Otherwise report the version that would be initialized.
   * @param {WithTimeoutOptions} [options]
   * @returns {Promise<number>}
   */
  async function version (options) {
     // ...
  }
  return withTimeoutOption(version)
}

1. ESLint reports error due to lack of @return annotation on outer function with: Missing JSDoc @returns for function.eslintvalid-jsdoc
2. TS infers return type of the outer function just fine, because version function is annotated (and knownig withTimeoutOption it can conclude type is same as of version function).
3. Reader could also clearly infer return type (assuming knowledge of withTimeoutOption) without any tools.

Image illustrating above two point.

Describe the solution you'd like

Listing them in order of preference:

1. Ideally ESLint would only raise error if return type can't be inferred.
2. Maybe ESLint could recognize dependency injection pattern and do only demand @return on outer function if inner one does not have annotations.
3. Remove @return annotation requirement (or turn it into warning ?). Annotations aren't required but adding any seems to require adding all.

Describe alternatives you've considered

I have considered alternative defining @callback type annotation as per TS JSDoc handbook

/**
 * If the repo has been initialized, report the current version.
 * Otherwise report the version that would be initialized.
 * @callback Version
 * @param {WithTimeoutOptions} [options]
 * @returns {Promise<number>}
 */

/**
 * @typedef {Object} Config
 * @property {Repo} repo
 *
 * @param {Config} config
 * @returns {Version}
 */
module.exports = ({ repo }) => {
  async function version (options) {
  // ...
  }
  return withTimeoutOption(version)
}

However that seems to make type script unable to infer some types in some cases, in the example above it reports: Parameter 'options' implicitly has an 'any' type.ts(7006).

You could make TS happy by adding /** @type {Version} */ comment but that in turn makes ESLint unhappy, leading to following error: Missing JSDoc for parameter 'options'.eslintvalid-jsdoc in the following code:

/**
 * If the repo has been initialized, report the current version.
 * Otherwise report the version that would be initialized.
 * @callback Version
 * @param {WithTimeoutOptions} [options]
 * @returns {Promise<number>}
 */

/**
 * @typedef {Object} Config
 * @property {Repo} repo
 *
 * @param {Config} config
 * @returns {Version}
 */
module.exports = ({ repo }) => {
  /** @type {Version} */
  async function version (options) {
  // ...
  }
  return withTimeoutOption(version)
}

[hugomrdias]

this will probably go way when the TS PR gets merged because it included a new jsdoc plugin for eslint

[hugomrdias]

The new eslint config fixes this.
Feel free to re open if this still happens.

Thank you 🙏🏼