The Java engineers at my company told me about Javadoc... I didn't even think to look for JSDoc... but it's essentially the same. I haven't needed to extract the Javadoc code into a MSWord document, but I think such tools already exist. I'll ask around. The other day when I gave Aptana a trial-run I was happily surprised to see it reading my Javadoc comments into a tooltip when I paused while thinking "what parameters does this function take again"...
But the biggest benefit is just in having consistent commenting of functions. For instance, the Javadoc for my plug-in will read something like: /** * hoverIntent is similar to jQuery's built-in "hover" function except that * instead of firing the onMouseOver event immediately, hoverIntent checks * to see if the user's mouse has slowed down over the object (beneath the * sensitivity threshold) before firing the onMouseOver event. * * hoverIntent r4 // 2007.03.26 // jQuery 1.1.2 * <http://cherne.net/brian/resources/jquery.hoverIntent.html> * * hoverIntent is currently available for use in all personal or commercial * projects under both MIT and GPL licenses. This means that you can choose * the license that best suits your project, and use it accordingly. * * // basic usage (just like .hover) receives onMouseOver and onMouseOut functions * $("ul li").hoverIntent( showNav , hideNav ); * * // advanced usage receives configuration object only * $("ul li").hoverIntent({ * sensitivity: 2, // number = sensitivity threshold (must be 1 or higher) * interval: 50, // number = milliseconds of polling interval * over: showNav, // function = onMouseOver callback (required) * timeout: 0, // number = milliseconds delay before onMouseOut function call * out: hideNav // function = onMouseOut callback (required) * }); * * @param f onMouseOver function || An object with configuration options * @param g onMouseOut function || Nothing (use configuration options object) * @return The object (aka "this") that called hoverIntent, and the event object * @author Brian Cherne <[EMAIL PROTECTED]> */ (function($) { $.fn.hoverIntent = function(f,g) { .... .... }; })(jQuery); Now that's rather verbose, but I'm sure it'll help a year from now when I've forgotten all about it. :) Brian. On 3/26/07, Matt Kruse <[EMAIL PROTECTED]> wrote:
>- javadoc commenting of plug-in external interface Using what tool? jsDoc? I've found that jsDoc works great for class-based structures, but not so well for stand-along functions or library interfaces like jquery plugins. There should be some standard javadoc-style syntax, but not necessarily exactly as used in jsdoc. In any event, I think all plugins should certainly have embedded API documentation, and the jquery.com site itself should be able to present each plugin's API docs in the same format, using the same tool. I would also suggest implementing additional jquery-specific doc tags for dependencies, etc. I've yet to find a tool that I really like to parse and report on these javadoc-style tags with the flexibility that I want. I don't even want a js parser - I can provide the full documentation, function name, parameters, etc within my comments. So I started writing a tool in php that will output the documentation on-the-fly. Of course, it's about 10% done, like most things I start... Matt _______________________________________________ jQuery mailing list discuss@jquery.com http://jquery.com/discuss/
_______________________________________________ jQuery mailing list discuss@jquery.com http://jquery.com/discuss/
