Menu
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.
781
JsDoc is a great tool for documenting code and providing type-safety in your JavaScript project without any additional configuration. Learn what JsDoc is, how it works, the benefits it provides, and how to use it in your project.
By default, JSDoc uses the built-in "default" template to turn the documentation into HTML. You can edit this template to suit your own needs or create an entirely new template if that is what you prefer. This command will create a directory named out/ in the current working directory.
JSDoc is a markup language used to annotate JavaScript source code files. Using comments containing JSDoc, programmers can add documentation describing the application programming interface of the code they're creating.
Press Ctrl+Shift+O for viewing all the methods and corresponding JSDoc opens up when you select a method there and hover over the method.
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.
172
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
21
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
