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

是否有可能告诉jsdoc查看与源代码分开的文件以获取该代码的文档？

2 个答案: