我如何在comments/JSDoc中引用另一个打字稿类型？

Question

我对Javadoc很熟悉.在Javadoc中,您可以放置​​一个引用Javadoc的链接放在另一个类型上,如下所示:

/**
 * 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{ /*...*/ }

我可以在打字稿的JSDoc风格中做同样的事情吗？我知道我可以在评论中使用markdown,我可以放置网页链接,但这不是我想要的.

此外,任何对JSDoc/typescript文档工具的引用都会非常有用:)

编辑:根据下面的答案,这是JSDoc的一个功能,但似乎没有包含在VSCode中.VSCode中是否有有效的语法？

Answer 1

VS Code 将其{@link}视为注释，因此不会进行任何特殊解析（它只是按照您键入的方式显示）。但是，目前有一个未解决的问题可以解决此问题。

Answer 2

使用 VSCode 1.52（2020 年 11 月），您还可以考虑使用另一个标签：

最初支持 JSDoc@see标签

JSDoc@see标签允许您在 JSDoc 注释中引用其他函数和类。

下面的示例显示了从另一个文件引用 WrappedError 类的崩溃函数：

// @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 现在将在执行重命名时包含基本的 @see 引用。

您还可以对@see标签的内容运行 go to definition ，@see 标签也将显示在引用列表中。

我们计划在未来的版本中继续改进对 @see 标签的支持。

正如马克在评论中指出的那样：

• PR 119358在 VSCode 1.55（2021 年 3 月）中添加了对 JSDoc 链接标签的支持
• VSCode 1.57（2021 年 5 月）增加了@link支持

JSDoc@link支持

我们现在支持JavaScript 和 TypeScript 注释中的JSDoc@link标签。

这些使您可以创建指向文档中符号的可点击链接：

JSDoc@link标签写成：{@link symbolName}.

您还可以选择指定要渲染的文本来代替符号名称：{@link class.property Alt text}。

@link支持悬停、建议和签名帮助。
我们还更新vscode.d.ts了使用@link.

Answer 3

你确定可以,虽然你的里程可能会有所不同.

1:在Selenium-Webdriver的TypeScript输入文件中使用@link

2:关于JSDoc中@link的文档

链接破坏时链接内容:

1:在Selenium-Webdriver的TypeScript输入文件中使用@link

/** * 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:关于JSDoc中@link的文档

以下示例显示了为{@link}标记提供链接文本的所有方法:提供链接文本

/**
 * 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() {}

默认情况下,上面的示例生成类似于以下内容的输出:{@link}标记的输出

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>.