16

我知道周围有各种各样的 JSDoc。似乎每个 JSDoc 解析器的实现都可以识别自己的一组标签。例如，考虑http://usejsdoc.org/和http://www.techrepublic.com/blog/programming-and-development/create-useful-relevant-javascript-documentation-with-jsdoc/之间的标签差异451 .

在这一点上，我只是感到困惑。是否有 JSDoc 的规范实现或广泛认可的核心标签集？是否有JSDoc 的最佳实现？

编辑

正如下面评论中所问的，这个问题的原因是我需要解析 JSDoc 评论以与我们正在创建的工具一起使用。看到这个问题”：有没有用 Javascript 编写的开源 JSDoc 解析器？

我担心我将不得不推出自己的解析器，如果这样做，我需要知道需要支持哪些标签。

但是，在更深层次上，我担心没有一致的规范（或参考实现）。这让 JSDoc 对我来说有点特别。

4

2 回答 2

5

我认为功能最完整的是谷歌闭包编译器使用的那个

使用 google 闭包编译器的一件很酷的事情是它会对你的函数进行类型检查，这些函数已经标记了类型信息。

我感觉到你的痛苦，我整天都在处理这件事。这是我必须编写代码/文档的非标准功能的示例。Ext-JS用于@cfg记录传递给小部件的初始化对象的属性。我使用的 IDE IntelliJ 使用 JSDoc 来提供更好的代码建议，它甚至可以理解 Ext 的方言。对于大多数事情，它运作良好。但是，很多时候我必须以某种方式复制文档以使我的 IDE 和 doc 工具（Ext 的 jsdoc 版本）都能理解它，而不是很干燥。这是一个例子：

...
/** 
 * @cfg {string} title // Ext-JS grabs the type from this line
 * @type string // My IDE grabs the type from this line
 */
 title: null // My IDE requires this line to recognize the cfg
             // as a property of the object even though all cfgs
             // are available in the object
...
于 2012-08-07T18:19:39.653 回答
4

我也分担你的痛苦。令人讨厌的是，这不是标准化的。虽然我同意 Juan Mendes 先生的观点，即 Closure Compiler 的功能是最完整的（并且可能是最棒的！），

我一直认为在这里找到的标签列表http://code.google.com/p/jsdoc-toolkit/w/list是我们拥有的最接近真实规范的东西。它可能已经过时了，但它仍然可能更接近许多解析器和 IDE 实现的东西，比 Closure Compiler 更接近。

另请参阅 Wikipedia，以了解关于应该存在哪些标签的最低限度的共识。http://en.wikipedia.org/wiki/JSDoc

尽管如果您的产品支持 JSDoc 的 Closure Compiler 风格，那将使它更接近成为事实上的标准。:D

于 2012-08-27T23:02:17.570 回答