typescriptjsdoc

TypeScript: is there a way to use the JSDOC @deprecated tag to mark a symbol imported from a module as deprecated?

I would like to mark a symbol as deprecated when imported from an 3rd party module. In the following example bar is some npm module that exports the function foo and I would like to mark foo as deprecated to inform that this api should no longer be used.

import {foo} from 'bar';

foo();
Solution

  • As far as I can tell, the @deprecated tag must be written at the declared site of the symbol that's imported.

    I tried creating two test repos and used declaration merging with declare module..., but got the following error:

    Cannot redeclare block-scoped variable 'foo'. ts(2451)

    As a workaround, you can import the function in your own module and assign it to a new variable, applying whatever documentation you'd like — then re-export it for use in your other modules. For example:

    ./src/bar.ts:

    import { foo as fooImport } from "bar";

/** @deprecated */
export const foo: typeof fooImport = fooImport;

    ./src/another_module.ts:

    import { foo } from "./bar";

foo();
//^? Will have the @deprecated JSDoc