为什么jQuery不使用JSDoc？ [英] Why Doesn't jQuery use JSDoc?

问题描述

或者他们和它们不在源头？我真的希望得到一些可以阻止js-doc-toolkit在每次解析jQuery时发现的东西。这也意味着我无法使用jQuery作为依赖关系来正确地记录任何代码，而不至少放置一些不正确地记录jQuery结构的样板js-doc块。有没有一个常见的解决方案我不知道？我试过googling，btw。

解决方案

我会在黑暗中拍摄，因为我不能说为什么我的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}）
 $ {$ {$ {$ {$ {$ {$}} {{height：5}，{duration：100，easing：linear}）
 .animate（{height：5}，{duration：100，easing：linear，complete：func}） 
  

所有这些都是有效的，因为参数类型根据需要进行检查和移位以支持尽可能的任何重载场景...这只是混淆了地狱的JSDoc，没有干净的方法来添加这些可选参数到文档。请更正我，如果这改变了，但是最后我看了（可能是最后一次这个团队的样子），这还是这样。

另一个潜在的考虑是如何当jQuery运行时，会生成一些方法，例如（其中一个），几乎所有的事件处理程序快捷方式是在循环中生成相似的行为对于其他方法...你会如何记录这些？ JSDoc一代在这里真的不太好。

Or do they and it's just not in the source? I'd really like to get something that will stop js-doc-toolkit from freaking out each time it parses jQuery. It also means I can't properly document any code using jQuery as a dependency without at least putting some boilerplate js-doc blocks, which fail to properly document jQuery's structure. Is there a common solution I'm not aware of? I have tried googling, btw.

解决方案

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():

.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 })

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.

这篇关于为什么jQuery不使用JSDoc？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！