(sorry Howard for hijacking your thread) Yes, the comments would be stripped from your compressed (packed/minified) code. However, there's nothing keeping you from copying/pasting a simplified comment block into the compressed code. So, for example, my minified plug-in would have the comment:
/** * hoverIntent r4 // 2007.03.26 // jQuery 1.1.2 * <http://cherne.net/brian/resources/jquery.hoverIntent.html> * * @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); Hopefully folks are submitting fully-commented/formated in addition to packed/minified files. This is even more important when you combine plug-in files together to reduce server requests... you'll need to keep track of where those plug-ins came from. This does fall apart on more complex plug-ins with multiple external interfaces. I can't think of one off the top of my head, but if your plug-in had a $().startPlugin *and* $().stopPlugin calls it would be hard to document that if they were contained in the same anonymous function($) call. Maybe using Javadoc as a standard is a nice-to-have, but not required...? Brian. On 3/26/07, Kenneth <[EMAIL PROTECTED]> wrote:
Oh no, you're actually correct then. I thought you were asking if you could compress the code with the documentation included, not the other way around... Yeah, since the compressed code is only meant to be used and not modified or read, the documentation would be stripped, and therefore running any tool to gather such information would return nothing I (or very little). And that's if *my" understanding is correct :P Sorry if I confused you! On 3/26/07, Christopher Jordan < [EMAIL PROTECTED]> wrote: > > Oh... that's exactly the reason I thought it *wouldn't* work. I don't > really understand javadocs... this is the first I've heard of them... > but it sounded like it took your comments and turned them into these > docs. I thought that since compressed js usually has the comments > stripped out, that it wouldn't work. > > I'm probably dead wrong, and should have just lurked this conversation, > huh? ;o) > > Chris > > Kenneth wrote: > > It should as long as the compressor removes comments. > > > > On 3/26/07, *Christopher Jordan* <[EMAIL PROTECTED] > > <mailto:[EMAIL PROTECTED]>> wrote: > > > > That wouldn't work for compressed JS would it? > > > > Chris > > > > Brian Cherne wrote: > > > 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 > > <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] > > <mailto:[EMAIL PROTECTED]> <mailto: [EMAIL PROTECTED] > > <mailto:[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] > > <mailto:[EMAIL PROTECTED]> > > > <mailto:[EMAIL PROTECTED] <mailto: [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 < http://jquery.com> > > <http://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 <mailto:discuss@jquery.com> <mailto: > > discuss@jquery.com <mailto:discuss@jquery.com >> > > > http://jquery.com/discuss/ <http://jquery.com/discuss/> > > > > > > > > > > > > > > > ------------------------------------------------------------------------ > > > > > > > > _______________________________________________ > > > jQuery mailing list > > > discuss@jquery.com <mailto:discuss@jquery.com> > > > http://jquery.com/discuss/ <http://jquery.com/discuss/> > > > > -- > > http://www.cjordan.us > > > > _______________________________________________ > > jQuery mailing list > > discuss@jquery.com <mailto:discuss@jquery.com> > > http://jquery.com/discuss/ > > > > > > > > > ------------------------------------------------------------------------ > > > > _______________________________________________ > > jQuery mailing list > > discuss@jquery.com > > http://jquery.com/discuss/ > > -- > http://www.cjordan.us > > _______________________________________________ > jQuery mailing list > discuss@jquery.com > http://jquery.com/discuss/ > _______________________________________________ jQuery mailing list discuss@jquery.com http://jquery.com/discuss/
_______________________________________________ jQuery mailing list discuss@jquery.com http://jquery.com/discuss/
