Field docs are ignored

[danfuzz]

Expected behavior

Documentation comments on field declarations — e.g. foo; or #foo = ...; etc. at the top level scope of a class — are scrutinized for valid doc comments, including feeding types into the "unused variable" calculations.

Actual behavior

Field declarations seem to be entirely ignored, for all combos of {public, private} x {static, instance}.

ESLint Config

module.exports = {
  extends: [
    "eslint:recommended",
    "plugin:jsdoc/recommended"
  ],
  plugins: ["jsdoc"],
  parserOptions: {
    "sourceType": "module",
    "ecmaVersion": "2022"
  }
};

ESLint sample

import * as net from 'node:net';

/** Likes are now florps. */
export class Florp {
  /** {net.Server} A server. */
  #privateField = null;

  /** {net.Server} A server. */
  publicField = null;

  /** {net.Server} A server. */
  static #privateStatic = null;

  /** {net.Server} A server. */
  static publicStatic = null;
}

Error:

$ ./node_modules/.bin/eslint Test.js 

/Users/danfuzz/tmp/linty/Test.js
  1:13  error  'net' is defined but never used  no-unused-vars

✖ 1 problem (1 error, 0 warnings)

Environment

• Node version: 18.7.0
• ESLint version 8.22.0
• eslint-plugin-jsdoc version: 39.3.6

[brettz9]

I am not aware of JSDoc types being used as you have done without an initial tag name. (I believe doing so would be ambiguous with curly brackets used as part of a block's main description text.)

If you add a tag, e.g.:

/** @type {net.Server} A server. */

...and then use it with plugin:jsdoc/recommended as you were doing (or with just the jsdoc/no-undefined-types rule which is currently responsible for marking JSDoc variables as used), no error should be reported.

FWIW, you may also wish to subscribe to #858 because we really should be moving to our own separate jsdoc/no-unused-vars rule rather than marking variables as used when our jsdoc/no-undefined-types is enabled. But for now, adding a tag name should resolve.

Closing as that should resolve, but feel free to comment further.

[danfuzz]

The last time I used JSDoc annotations was before class fields were settled syntax, and I just went with what seemed to me to be sensible (like, what else would I be documenting directly above a field declaration?). But that's on me and my faulty headcanon.

Thanks for the explanation! And sorry for the trouble.