Cool! Thanks for clarifying that for me. :o) Chris
Kenneth 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] > <mailto:[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]> > > <mailto:[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> > > <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]>> <mailto: > [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]>> > > > <mailto:[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> > > <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>> <mailto: > > 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> > <mailto:discuss@jquery.com <mailto:discuss@jquery.com>> > > > http://jquery.com/discuss/ <http://jquery.com/discuss/> > <http://jquery.com/discuss/> > > > > -- > > http://www.cjordan.us > > > > _______________________________________________ > > jQuery mailing list > > discuss@jquery.com <mailto:discuss@jquery.com> > <mailto:discuss@jquery.com <mailto:discuss@jquery.com>> > > http://jquery.com/discuss/ > > > > > > > > > ------------------------------------------------------------------------ > > > > _______________________________________________ > > jQuery mailing list > > discuss@jquery.com <mailto:discuss@jquery.com> > > 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/
