为什么jQuery不使用JSDoc?

Question

为什么jQuery不使用JSDoc?

javascriptjquerydocumentationstandardsjsdoc

31

他们是否存在，只是不在源代码中？我真的希望能找到一些东西，可以阻止js-doc-toolkit每次解析jQuery时出现问题。这意味着我无法正确地记录任何使用jQuery作为依赖项的代码，除非至少放置一些样板js-doc块，但这些块无法正确记录jQuery的结构。有没有我不知道的常见解决方案？顺便说一句，我已经尝试过谷歌搜索了。

- hlfcoding

重复的 jQuery 文档格式 ;) （遗憾的是，那里没有答案） - Marcel Korpel

2

有一个小更新，但我发现Docco更容易用来记录JS。找到正确的JSDoc标签真的很繁琐。个人认为Docco的文档策略更简单、更实际。还有Rocco，作为一个gem，它将与Cygwin更好地配合使用，因为不需要NPM。 - hlfcoding

2

Docco听起来是个不错的主意，除了这一点：“只处理单行注释——块注释会被忽略。”我认为，如果你正在编写API文档，块注释绝对是你想要处理的，因为它们更容易编写较长的解释。 - user4815162342

@user4815162342，实际上我喜欢这样。这样，我可以保留多行注释，仅用于注释闭包编译器指令。 - Camilo Martin

3个回答

7

不知道为什么他们没有添加JSDoc注释，但Google Closure团队似乎使用最新版本的“externs”来保持与高级优化闭包编译器的兼容。

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

- ʟɿʠʆɜʣʑɭʟʂɪəɬɸʛʌʢɑʓʔ

4

虽然我在原问题上不能提供其他人没有的内容，但我可以提供一个链接，其中包含可以自动记录 jQuery 的内容。

它通过在运行时环境中执行jQuery并解析生成的树来实现这一点。像JSDoc一样，它使用了修改后的Rhino。目前它还处于初期阶段，但我希望对某些人有所帮助。 :)

https://bitbucket.org/nexj/njsdoc

- Jasmine Hegman

JSDoc 确实进行静态分析。 - kzh

是的，它确实可以。如果你是这样理解的话，我并没有说它不能。我应该在这里澄清我的观点，即NJSDoc进行运行时（动态）分析而不是静态分析。试图通过更少的（理想情况下没有）样板提示注释来达到相同或更高水平的文档化。 - Jasmine Hegman

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- Nick Craver · Accepted Answer

我这里只是猜测，因为我不能代表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 })

以下内容均为有效内容，因为参数类型会根据需要检查和转换以支持尽可能多的重载情况...这只会让JSDoc感到困惑，没有清洁的方法将这些可选参数添加到文档中。如果有变化，请纠正我，但据我所知（也可能是团队最后一次查看时），情况仍然如此。

另一个潜在的考虑因素是当jQuery运行时，一些方法是如何生成的，例如（众多方法之一），几乎所有的事件处理程序快捷方式都是在循环中生成，其他方法也有类似的行为...你会如何记录这些？JSDoc生成在这里确实无法很好地工作。