javascript - 是否可以告诉 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:只是为了表明它可以用模块来完成。他们可以只是在不需要模块的情况下被剥离。