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?
JSDoc comments should generally be placed immediately before the code being documented. Each comment must start with a /** sequence in order to be recognized by the JSDoc parser. Comments beginning with /* , /*** , or more than 3 stars will be ignored.
The @typedef tag is useful for documenting custom types, particularly if you wish to refer to them repeatedly. These types can then be used within other tags expecting a type, such as @type or @param. Use the @callback tag to document the type of callback functions.
One huge benefit of using TypeScript and documenting with JSDoc syntax is that you can avoid having to specify JSDoc types in your docs! If you want to read the full specification check out Microsoft's standard, tsdoc.
You sure can, though your mileage may vary.
1: A use of @link
in Selenium-Webdriver's TypeScript typing file
/** * Converts a level name or value to a {@link logging.Level} value. * If the name/value is not recognized, {@link logging.Level.ALL} * will be returned. * @param {(number|string)} nameOrValue The log level name, or value, to * convert . * @return {!logging.Level} The converted level. */ function getLevel(nameOrValue: string | number): Level;
2: Docs about @link
in JSDoc
The following example shows all of the ways to provide link text for the {@link} tag: Providing link text
/** * See {@link MyClass} and [MyClass's foo property]{@link MyClass#foo}. * Also, check out {@link http://www.google.com|Google} and * {@link https://github.com GitHub}. */ function myFunction() {}
By default, the example above produces output similar to the following: Output for {@link} tags
See <a href="MyClass.html">MyClass</a> and <a href="MyClass.html#foo">MyClass's foo property</a>. Also, check out <a href="http://www.google.com">Google</a> and <a href="https://github.com">GitHub</a>.
VS Code treats {@link}
as a comment, so it doesn't get any special parsing (it's just displayed exactly as you typed it). There's currently an open issue to fix this, however.
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:
@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
.
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With