Issue
I'm familiar with Javadoc. In Javadoc, you can place a link that refers to the Javadoc placed on another type like so:
/**
* some java thingy. see this other java thingy too {@link OtherThingy}
*/
public class Thingy { /*...*/ }
/**
* some other java thingy. see the first java thingy too {@link Thingy}
*/
public class OtherThingy{ /*...*/ }
Can I do the same in typescript's flavor of JSDoc? I know that I can use markdown in the comments and I can place web links but that's not exactly what I'm going for.
Also, any references to JSDoc/typescript documentation tools would be very helpful :)
Edit: Per the answers below, this is a feature of JSDoc but doesn't seem to be included in VSCode. Is there an valid syntax in VSCode?
Solution
Yes, you can use @link
You can use {@link OtherThingy}
in docs, and it works in VS Code since 2021. If you want an inline reference, just use that.
Details and alternatives
With VSCode 1.52 (Nov. 2020), you might also consider another tag:
Initial support for JSDoc
@see
tagsJSDoc
@see
tags let you reference other functions and classes in your JSDoc comments.The example below shows crash function referencing the WrappedError class from another file:
// @filename: somewhere.ts export class WrappedError extends Error { ... } // @filename: ace.ts import { WrappedError } from './somewhere' /** * @see {WrappedError} */ function crash(kind) { throw new WrappedError(kind); }
VS Code will now include basic @see references while performing renames.
You can also run go to definition on the
@see
tag's content and @see tags will also show up in the list of references.We plan to continue improving support for @see tags in future releases.
As Mark notes in the comments:
- PR 119358 adds support for JSDoc link tags in VSCode 1.55 (March 2021)
- VSCode 1.57 (May 2021) adds
@link
support
JSDoc
@link
supportWe now support JSDoc
@link
tags in JavaScript and TypeScript comments.These let you create clickable links to a symbol in your documentation:
JSDoc
@link
tags are written as:{@link symbolName}
.You can also optionally specify text to be render in place of the symbol name:
{@link class.property Alt text}
.
@link
is supported in hovers, suggestions, and signature help.
We have also updatedvscode.d.ts
to use@link
.
Note: cachius adds in the comments:
import { MyClassName } from "path/to/MyClassName";
If
MyClassName
is not already imported, adding@see MyClassName
in the JSDoc would only showany
on hover and doesn't allow ctrl + clickthrough to declaration/usages.Importing it allows that, even if the only mention is in the JSDoc.
This is useful when a module/class refers to some other logically, but without using it directly.Unused imports might trigger
eslint
warnings though, which I'd silence in this case with:// eslint-disable-next-line @typescript-eslint/no-unused-vars
To that effect, Daniel Steigerwald adds in the comments
The imported type must be actually used.
Otherwise, JSDoc will not process.
And:
Another more serious issue is that destructuring removes any JSDoc part containing
@
, making it effectively useless. That's why I have to replace all@example
with Markdown, e.g.### Example ts ...
Eric Haynes adds in the comments:
Consider using instead:
import type { MyClassName } from 'path/to/MyClassName';
The type import will be elided at compile time, rather than adding an actual import in the compiled JavaScript.
(orimport { type MyClassName, OtherThing }
if you already have an import for something else on that path)
Answered By - VonC
0 comments:
Post a Comment
Note: Only a member of this blog may post a comment.