Suggestion

🔍 Search Terms

• is declared but its value is never read tsdoc
• is declared but its value is never read tsdoc @deprecated

✅ Viability Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
  • This will reduce compilation errors, so it would not break existing code.
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
  • This is a compilation error check only, so it wouldn't change any JS output.
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.
  • I've only skimmed through, but I didn't see anything that wouldn't align with the goals.

⭐ Suggestion

I sometimes use TSDoc to reference another type that isn't really being used in the file I'm working in. This is often in combination with the @deprecated documentation tag. My suggestion is to stop giving the compilation error that the import is not being used. I do realize it might be some complexity that I'm not aware of here, regarding looking at the contents of the TSDocs.

📃 Motivating Example

import myNotDeprecatedFunction from "./other-file.ts";

/**
 * @deprecated Use {@link myNotDeprecatedFunction} instead.
 */
export const myDeprecatedFunction = () => {
    console.log("Hello world");
};

As you can see, I import the other function, and this is to make sure that the link works when viewing TSDocs in VSCode (or any other IDE I'd assume). But TypeScript will complain about this import never being read. I would love to see this warning go away when I'm referencing it in a {@link}.

💻 Use Cases

It simply improves my documentation without workarounds to get around the error

Other notes

I also added a similar issue for the TSLint project:
typescript-eslint/typescript-eslint#5017