I'll take a shot in the dark here since I can't speak for the jQuery team of why I wouldn't use JSDoc. JSDoc, at least the last time I checked, didn't have any clean way to support method overloading (or parameter shifting...whatever name you want to give it here) and jQuery uses this all over the place. Let's take a simple common example with .animate():
All of these are valid, since parameter types are checked and shifted as needed to support as any overload scenarios as possible...this just confuses the hell out of JSDoc, there's no clean way to add these optional parameters to the documentation. Please correct me if this has changed, but last I looked (and probably the last time the team took a look) this was still the case.
Another potential consideration is how some methods are generated when jQuery runs, for example (one of many), almost all the event handler shortcuts are generated in a loop similar behavior for other methods...how would you document these? JSDoc generation just really doesn't work well here.
Don't know why they don't add the JSDoc comment but the Google Closure guys seem to keep an updated version of the "externs" they need for the closure compiler with advanced optimization
While I cannot add anything else that others haven't regarding the original question, I can provide a link to something that CAN automatically document jQuery.
It does this by executing it in a runtime environment, and then parsing the resulting trees. Like JSDoc it uses a modified Rhino. It's in its infancy but I hope this comes in handy for someone. :)
发布评论
评论（3）
我将在这里尝试一下，因为我无法代表 jQuery 团队解释为什么我不会使用 JSDoc。 JSDoc，至少我上次检查时，没有任何干净的方法来支持方法重载（或参数转移......无论你想在这里给它起什么名字），而 jQuery 在各处都使用它。让我们以
.animate()为例：所有这些是有效的，因为参数类型根据需要进行检查和转移 尽可能支持任何重载场景...这只会让 JSDoc 感到困惑，没有干净的方法将这些可选参数添加到文档中。如果情况发生了变化，请纠正我，但我上次查看（可能是团队最后一次查看）情况仍然如此。
另一个潜在的考虑因素是 jQuery 运行时如何生成某些方法，例如（许多方法之一），几乎所有 事件处理程序快捷方式 在循环中生成< /a> 其他方法的类似行为...您将如何记录这些？ JSDoc 生成在这里确实不能很好地工作。
I'll take a shot in the dark here since I can't speak for the jQuery team of why I wouldn't use JSDoc. JSDoc, at least the last time I checked, didn't have any clean way to support method overloading (or parameter shifting...whatever name you want to give it here) and jQuery uses this all over the place. Let's take a simple common example with
.animate():All of these are valid, since parameter types are checked and shifted as needed to support as any overload scenarios as possible...this just confuses the hell out of JSDoc, there's no clean way to add these optional parameters to the documentation. Please correct me if this has changed, but last I looked (and probably the last time the team took a look) this was still the case.
Another potential consideration is how some methods are generated when jQuery runs, for example (one of many), almost all the event handler shortcuts are generated in a loop similar behavior for other methods...how would you document these? JSDoc generation just really doesn't work well here.
不知道为什么他们不添加 JSDoc 注释，但 Google Closure 人员似乎保留了闭包编译器所需的“外部程序”的更新版本，并进行了高级优化
http://code.google.com/p/closure-compiler/source/browse/主干/contrib/externs/jquery-1.6.js?r=1152
Don't know why they don't add the JSDoc comment but the Google Closure guys seem to keep an updated version of the "externs" they need for the closure compiler with advanced optimization
http://code.google.com/p/closure-compiler/source/browse/trunk/contrib/externs/jquery-1.6.js?r=1152
虽然我无法添加其他人没有就原始问题添加的任何内容，但我可以提供一个可以自动记录 jQuery 的链接。
它通过在运行时环境中执行它，然后解析生成的树来实现这一点。与 JSDoc 一样，它使用经过修改的 Rhino。它还处于起步阶段，但我希望这对某人有用。 :)
https://bitbucket.org/nexj/njsdoc
While I cannot add anything else that others haven't regarding the original question, I can provide a link to something that CAN automatically document jQuery.
It does this by executing it in a runtime environment, and then parsing the resulting trees. Like JSDoc it uses a modified Rhino. It's in its infancy but I hope this comes in handy for someone. :)
https://bitbucket.org/nexj/njsdoc