Why Doesn't jQuery use JSDoc?

Question

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.

Solution 1

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.

Solution 2

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

Solution 3

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