31

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.

hlfcoding
  • 2,532
  • 1
  • 21
  • 25
  • Duplicate of [jQuery Documentation Format](http://forum.jquery.com/topic/jquery-documentation-format) ;) (Alas, no answer there) – Marcel Korpel Oct 29 '10 at 08:51
  • 2
    A bit of an update, but I found [Docco](http://jashkenas.github.com/docco/) is much easier to document JS with. It's really tedious to find the right JSDoc tag. Personally, I find Docco's documentation strategy simpler and more realistic. There's also [Rocco](https://github.com/rtomayko/rocco#readme), which, as a gem, will work with Cygwin better, since NPM isn't required. – hlfcoding Aug 06 '11 at 00:06
  • 2
    Docco sounds like a good idea, except for this: "Only single-line comments are processed -- block comments are ignored." It seems to me that the block comments are the ones you definitely want to process if you're writing API docs, since it's easier to write long bits of explanation in them. – user4815162342 Sep 11 '12 at 13:33
  • @user4815162342 Actually I like that. That way, I can keep multi-line comments for annotating closure compiler directives only. – Camilo Martin Sep 26 '12 at 00:30

3 Answers3

30

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.

Scott Rippey
  • 15,614
  • 5
  • 70
  • 85
Nick Craver
  • 623,446
  • 136
  • 1,297
  • 1,155
  • 1
    I think the inability to document parameters to be totally correct isn't the biggest concern. I'm more concerned why objects and methods themselves can't at least be documented, so that JSDoc at least knows they exist and where to reference to. And one potential benefit of generating docs for a jQuery project is to have an easier time upgrading it from big changes to jQuery source. Is there a better doc generator out there? I've heard of Docco... – hlfcoding Oct 29 '10 at 10:36
  • @hlfcoding - I'm not sure if there's a better alternative, honestly I live in Visual Studio most of the time, and there's a provided `-vsdos.js` that is uses...some the Microsoft guys or community generate: http://stackoverflow.com/questions/2323366/jquery-1-4-2-vsdoc The editor depends on that documentation to tell you what the parameters are, if they're inaccurate all the time (and several methods are generated on the fly...how do you document them in source?) then they're not very useful. – Nick Craver Oct 29 '10 at 10:54
  • @Nick I was just wondering the same thing. I use the `-vsdoc.js` files and just thought, "Why does Microsoft have to do this differently than most?" I didn't consider it was because of jQuery's 'type-checking' of parameters. Nice example on that front. Side note: @hlfcoding has `666` rep points. – Joseph Yaduvanshi Jul 05 '11 at 13:55
  • It makes static type checking much less useful, but these overloads can be declared with JSDoc: {string|Object|Number} for example - so if there are 5 parameters and all might be shifted, the first parameter ends up with a pretty crazy list of possible types. You can punt with {*} if it really could be anything. You could make each shift call another more strongly-typed function to catch all static type issues, and hope Closure Compiler with ADVANCED_OPTIMIZATIONS inlines things enough to eliminate the performance burden - but that's a big bet and a lot of extra work. – Chris Moschini Oct 19 '11 at 21:43
  • @Chris - that's not really true, since declaring the types that way results in a multitude of invalid combinations of parameters. For example param #2 may be a function but only if param #1 isn't, etc...so declaring docs that way is very misleading, and outright incorrect in *most* of the combinations it'd produce. – Nick Craver Oct 20 '11 at 02:03
  • It would prevent more erroneous cases than not applying JSDoc to them at all. Ultimately parameter shifting in JQuery needs the compiler to actually execute the JS a few steps to really determine what is and is not valid. It doesn't appear Closure or MS Ajax do that quite yet. – Chris Moschini Oct 20 '11 at 05:05
  • @Chris - indeed they don't...which is also another reason jQuery doesn't use Closure anymore :) – Nick Craver Oct 20 '11 at 10:11
  • @Chris - JSDoc allows optional parameters by surrounding the type with square brackets, e.g. `{[int]} duration`. This would handle the overloading assume that the order is consistent. It wouldn't handle the parameters-stuffed-into-an-object case, however. – David Harkness Jun 25 '12 at 15:23
  • 2
    JSDoc also has the `@variation` tag which is useful for documenting different ways in which a method may be called. – kzh Jul 22 '13 at 14:02
7

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

ʟɿʠʆɜʣʑɭʟʂɪəɬɸʛʌʢɑʓʔ
  • 71
  • 1
  • 1
4

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

Jasmine Hegman
  • 547
  • 7
  • 22
  • JSDoc does do static analysis. – kzh Jul 22 '13 at 14:01
  • Yes it does. I was not saying that it didn't, if that is how you took it. I should have clarified my point here, which was that NJSDoc does run-time (dynamic) analysis instead of static analysis. Attempting to achieve the same level (or greater) of documentation with fewer (ideally none) boilerplate hint annotations. – Jasmine Hegman Dec 10 '13 at 17:56