如何在评论/JSDoc 中引用另一种打字稿类型？

Posted 2023-03-13

技术标签:

【中文标题】如何在评论/JSDoc 中引用另一种打字稿类型？【英文标题】：How do I refer to another typescript type in comments/JSDoc? 【发布时间】：2017-11-02 12:29:48 【问题描述】：

我熟悉 Javadoc。在 Javadoc 中，you can place a link that refers to the Javadoc placed on another type 是这样的：

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

我可以在 typescript 的 JSDoc 中做同样的事情吗？我知道我可以在 cmets 中使用 markdown 并且可以放置网络链接，但这并不是我想要的。

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

编辑：根据下面的答案，这是 JSDoc 的一个功能，但似乎不包含在 VSCode 中。 VSCode 中有有效的语法吗？

【问题讨论】：

【参考方案1】：

您当然可以，尽管您的里程可能会有所不同。

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

以下示例显示了为 @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>.

【讨论】：

我可能应该尝试一下 javadoc 的语法吧？我刚开始使用typedoc，它支持@link。你的答案值得检查【参考方案2】：

VS Code 将@link 视为注释，因此它不会进行任何特殊解析（它只是完全按照您输入的方式显示）。不过，目前有 an open issue 来解决这个问题。

【讨论】：

请参阅上面关于@link supprot 的评论。【参考方案3】：

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

Initial support for JSDoc @see tags

JSDoc @see 标签让您可以在您的 JSDoc cmets 中引用其他函数和类。

以下示例显示了从另一个文件引用 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 标记的支持。

正如马克在the comments 中指出的那样：

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

JSDoc@link 支持

我们现在在 javascript 和 TypeScript cmets 中支持 JSDoc @link tags。

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

JSDoc @link 标签写为：@link symbolName.

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

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