是否有可能告诉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

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

{@tutorial} 教程

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

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

用法：

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