有没有 JSDoc 标准？答案

【问题标题】：Is there a JSDoc standard?有没有 JSDoc 标准？
【发布时间】：2013-06-19 04:57:18
【问题描述】：

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

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

编辑

正如下面评论中所问的，这个问题的原因是我需要解析 JSDoc cmets 以与我们正在创建的工具一起使用。看到这个问题”：Are there any open source JSDoc parser written in Javascript?

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

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

【问题讨论】：

了解您的具体问题会有所帮助。您是否正在从一个文档生成工具切换到另一个文档生成工具？或者这是一个假设，因此您将来可以拥有灵活性？您想使用哪些标签不是在所有实现中？
恐怕 JSDoc 还不是标准。有点像有 JScript 和 JavaScript，但没有 ECMAScript
对...但是如果没有标准（大写'S'）我没关系，但想知道是否有非官方标准（小's'）的使用方式以及实现它的工具。

标签： javascript standards jsdoc

【解决方案1】：

我认为功能最完整的是google closure compiler使用的那个

使用 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
...

【讨论】：

最后，我们使用闭包编译器语法。它似乎是我发现的所有 jsdoc 风格中最完整且记录最完整的。

【解决方案2】：

我也分担你的痛苦。令人讨厌的是，这不是标准化的。虽然我同意 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

【讨论】：