是否有可能告诉jsdoc查看与源代码分开的文件以获取该代码的文档？ [英] Is it possible to tell jsdoc to look in a file separate from the source code for documentation of that code?

问题描述

我希望尽可能缩短内联评论，因为我的经验是超过3或4行的评论往往被掩盖，创造了许多不必要的阅读手册。

I would like to keep inline comments as short as possible, since my experience is that comments of more than 3 or 4 lines tend to be glossed over, creating a lot of unnecessary "read the manual lines".

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

I'm required by legacy to adhere to a jsdoc-compatible format for documenting code. It requires that a lot of self evident things be declared explicitly if they're to be documented correctly. Practically every tag can fall in this category. Even the ones that don't are often useless to a working developer.

我的愿景是在开发人员实际阅读的代码本身内快速总结一下，但是参考到一个单独的文件（甚至是同一文件中的注释转储，与开发人员工作的地方分开）进行额外的标记，如下所示：

My vision is to have a quick summary inside the code itself that developers will actually read, but refer to a separate file (or even a comment dump in the same file, separate from where developers will be working) for additional tagging, like this:

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

一个不同的工具或插件是可以接受的，我真的只是坚持语法。另一个替代方案是使用一些非常好的隐式文档创建工具

A different tool or a plugin would be acceptable, I'm really only stuck with the syntax. Another alternative would be a tool with some really good implicit documentation creation

推荐答案

使用jsdoc3，我认为没有办法无需编写新插件即可获得完美的
解决方案。 （我不知道已经做的
插件。）

With jsdoc3, I do not think there is a way to get what a perfect solution without having to write a new plugin. (I do not know of a plugin that would already do it.)

但是，有可能滥用jsdoc标签来获得
不完美但功能正常的东西。

However, it is possible to abuse the jsdoc tags to get something which is not perfect but is functional.

/**
 * @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 和模块：
就是为了表明它可以用模块来完成。对于不需要模块的情况，它们可以被剥离
。

The key is to create a type definition with a unique name, and then use @see to link to that definition. @module and module: are just there to show it can be done with modules. They can just be stripped for cases where modules are not needed.

这篇关于是否有可能告诉jsdoc查看与源代码分开的文件以获取该代码的文档？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！