是否可以告诉 jsdoc 在与源代码分开的文件中查找该代码的文档？

Question

我希望内联注释尽可能短，因为我的经验是超过 3 或 4 行的注释往往会被掩盖，从而产生很多不必要的“阅读手册行”。

遗留要求我遵守与 jsdoc 兼容的格式来记录代码。 如果要正确记录许多不言而喻的事情，则需要明确声明它们。 实际上每个标签都可以属于这一类。 即使那些没有的对于正在工作的开发人员来说通常也是无用的。

我的愿景是在代码本身中有一个快速摘要，供开发人员实际阅读，但参考单独的文件（甚至是同一文件中的注释转储，与开发人员将工作的位置分开）以获得额外的标记，如下所示:

/**
 *  Used when making an example of the argument.
 *  @include someotherplace
 */
function example(argument) { stuff;}

...lots more code...

/**
 *  someotherplace
 *  @param argument The victim
 *  @since forever
 *  @other stuff
 */

不同的工具或插件是可以接受的，我真的只坚持语法。 另一种选择是一个具有一些非常好的隐式文档创建的工具

Answer 1

使用 jsdoc3，我认为没有办法获得如此完美的结果 解决方案，无需编写新插件。 （我不知道有一个 插件已经可以做到这一点。）

但是，有可能滥用 jsdoc 标签来获取某些内容 并不完美，但很实用。

/**
 * @module foo
 */


/**
 * Used when making an example of the argument.
 * @see {module:foo.example_type}
 */
function example(argument) {
    //...
}

/**
 * someotherplace
 * @typedef {function} module:foo.example_type
 * @param argument The victim
 * @since forever
 */

关键是创建一个具有唯一名称的类型定义，然后 使用

@see

链接到该定义。

@module

和

module:

只是为了表明它可以通过模块来完成。他们可以只是 在不需要模块的情况下被剥离。

Answer 2

{@link} 标签和教程 {@tutorial} 标签怎么样？来自文档：

{@tutorial} 教程

教程机制让您不仅可以包含简短的代码相关技术 API 文档，还可以包含更长、更解释性的整页教程

{@link} 标签允许您从任何标签描述的文本中创建指向其他记录符号的 HTML 链接。

用途：

@anyTag This is some text {@link otherSymbol}.

Answer 3

我正在使用 vscode，发现你只需要导入你想要引用的函数/变量，链接就开始工作：

/**
 * @deprecated Use {@link func} instead
 */
const func_deprecated = () => {}