What tools are available for documenting jQuery plugins?

Question

Hi,

I've recently started creating some jQuery plugins and I'm finding it difficult to document them with the documentation generating tools that I've found. I've tried: JSDoc, JSDoc-toolkit, JGrouse and a web-based tool also. My biggest headache is that my plug-ins are coded as one big anonymous function, and I'm having trouble getting the tools to either recognize what I'm doing, or ignore it altogether and let me type in the documentation tags for the methods, objects, etc..

Are there any other tools that might help with documenting jQuery plugins?

Thanks, Sandro

Answer 1

Javascript documentation tools are still relatively immature, so there aren't 50+ ones like there are for say JavaDoc, and the ones that do exist don't handle complex cases like jQuery plug-ins (or at least none of the ones I've ever seen).

However, Javascript is an extremely flexible language, so you could just rewrite your plug-ins in a way that makes your documentation tool happy.

For instance, instead of:

(function($) {
    $.yourMethod = function() {/* do something */}
})(jQuery);

you could do:

function yourMethod = function() {
    /* do something */
}

(function($) {
    $.yourMethod = yourMethod;
})(jQuery);
delete yourMethod

or just:

jQuery.yourMethod = function() {
    /* do something */
}

Those two options aren't truly identical; the first one will overwrite any existing yourMethod function, and the latter will not have the nice "privacy" of the standard plug-in format. Depending on what you're writing this plug-in for, those issues may or may not matter to you.

If they don't, re-styling your code may be a viable way of making your JSDoc parsable. If not ... good luck finding a mature enough JSDoc tool (or writing your own) :-)

Answer 2

I use Visual Studio XML comments: http://weblogs.asp.net/bleroy/archive/2007/04/23/the-format-for-javascript-doc-comments.aspx

Answer 3

Have you had a look at Natural Docs? It might not have very much of explicit support for JavaScript, however it does a quite good job anyway. Of course you can trick it not to understand the code, but if you play nice with it, it can be a hell of a tool.