为什么 jQuery 不使用 JSDoc？ [关闭]答案

【问题标题】：Why Doesn't jQuery use JSDoc? [closed]为什么 jQuery 不使用 JSDoc？ [关闭]
【发布时间】：2014-02-14 01:08:38
【问题描述】：

或者他们只是不在源代码中？我真的很想得到一些东西来阻止 js-doc-toolkit 每次解析 jQuery 时都吓坏了。这也意味着我不能正确地记录使用 jQuery 作为依赖项的任何代码，而至少不放置一些样板 js-doc 块，这些块无法正确记录 jQuery 的结构。有我不知道的通用解决方案吗？顺便说一句，我试过谷歌搜索。

【问题讨论】：

jQuery Documentation Format 的重复；）（唉，那里没有答案）
有点更新，但我发现Docco 更容易记录 JS。找到合适的 JSDoc 标签真的很乏味。就个人而言，我发现 Docco 的文档策略更简单、更现实。还有Rocco，作为gem，它可以更好地与Cygwin 配合使用，因为不需要NPM。
Docco 听起来是个好主意，除了这个：“只处理单行 cmets -- 忽略块 cmets。”在我看来，如果您正在编写 API 文档，那么块 cmets 是您肯定要处理的，因为在其中编写长解释会更容易。
@user4815162342 其实我喜欢这样。这样，我可以保留多行 cmets 仅用于注释闭包编译器指令。

标签： javascript jquery documentation standards jsdoc

【解决方案1】：

我将在这里暗中尝试，因为我不能代表 jQuery 团队说明为什么我不会使用 JSDoc。 JSDoc，至少在我最后一次检查时，没有任何干净的方法来支持方法重载（或参数转换......你想在这里给它起什么名字），而 jQuery 到处都在使用它。让我们以.animate() 为例：

.animate({ height: 5 })
.animate({ height: 5 }, 100)
.animate({ height: 5 }, 100, "linear")
.animate({ height: 5 }, 100, "linear", func)
.animate({ height: 5 }, 100, func)
.animate({ height: 5 }, func)
.animate({ height: 5 }, { duration: 100, queue: false })
.animate({ height: 5 }, { duration: 100, easing: "linear" })
.animate({ height: 5 }, { duration: 100, easing: "linear", complete: func })

所有这些都是有效的，因为parameter types are checked and shifted as needed 尽可能支持任何重载场景......这只会让 JSDoc 感到困惑，没有干净的方法可以将这些可选参数添加到文档中。如果这种情况发生了变化，请纠正我，但我最后一次查看（可能是团队最后一次查看）仍然是这种情况。

另一个潜在的考虑是在 jQuery 运行时如何生成一些方法，例如（许多方法之一），几乎所有 event handler shortcuts 都是 generated in a loop 与其他方法类似的行为......你将如何记录这些？ JSDoc 生成在这里真的不能很好地工作。

【讨论】：

我认为无法完全正确地记录参数并不是最大的问题。我更关心为什么对象和方法本身至少不能被记录，以便 JSDoc 至少知道它们存在以及在哪里引用。为 jQuery 项目生成文档的一个潜在好处是可以更轻松地将其从重大更改升级到 jQuery 源代码。那里有更好的文档生成器吗？我听说过 Docco...
@hlfcoding - 我不确定是否有更好的选择，老实说，我大部分时间都住在 Visual Studio 中，并且提供了一个 -vsdos.js 用于使用......一些微软的家伙或社区生成：stackoverflow.com/questions/2323366/jquery-1-4-2-vsdoc 编辑器依赖该文档来告诉您参数是什么，如果它们一直不准确（并且动态生成了几种方法......您如何在源代码中记录它们？）那么它们就不是很有用了。
@Nick 我只是想知道同样的事情。我使用-vsdoc.js 文件并只是想，“为什么微软必须以与大多数人不同的方式来做这件事？”我不认为这是因为 jQuery 对参数的“类型检查”。在这方面很好的例子。旁注：@hlfcoding 有666 代表点。
它使静态类型检查的用处大大降低，但这些重载可以用 JSDoc 声明：例如 {string|Object|Number} - 所以如果有 5 个参数并且所有参数都可能被转移，第一个参数最终得到一个非常疯狂的可能类型列表。如果它真的可以是任何东西，你可以用 {*} 下注。您可以让每个班次调用另一个更强类型的函数来捕获所有静态类型问题，并希望带有 ADVANCED_OPTIMIZATIONS 的闭包编译器内联足以消除性能负担的东西 - 但这是一个很大的赌注和很多额外的工作。
JSDoc 也有 @variation 标记，用于记录调用方法的不同方式。

【解决方案2】：

不知道他们为什么不添加 JSDoc 注释，但 Google Closure 的家伙似乎保留了他们需要的具有高级优化的闭包编译器的“externs”的更新版本

http://code.google.com/p/closure-compiler/source/browse/trunk/contrib/externs/jquery-1.6.js?r=1152

【讨论】：

【解决方案3】：

虽然我无法添加其他人没有关于原始问题的任何其他内容，但我可以提供指向可以自动记录 jQuery 的内容的链接。

它通过在运行时环境中执行它，然后解析生成的树来做到这一点。与 JSDoc 一样，它使用修改后的 Rhino。它还处于起步阶段，但我希望这对某人有用。 :)

https://bitbucket.org/nexj/njsdoc

【讨论】：

JSDoc 做静态分析。
是的。我不是说它没有，如果你是这样认为的。我应该在这里澄清我的观点，即 NJSDoc 进行运行时（动态）分析而不是静态分析。尝试使用更少（最好没有）样板提示注释来实现相同级别（或更高级别）的文档。