fluid-work IRC Logs-2008-03-12
- Fluid IRC Log Bot
[07:38:42 EDT(-0400)] * phiggins_ (n=dante@c-68-34-199-67.hsd1.tn.comcast.net) has joined #fluid-work <colinclark> @@echo " - Extracting ScriptDoc from" $ <colinclark> @@$ $ /docs/docs.js $ $
[09:38:59 EDT(-0400)] * EricDalquist (n=dalquist@bohemia.doit.wisc.edu) has joined #fluid-work
[09:50:28 EDT(-0400)] * theclown (n=theclown@142.150.154.101) has joined #fluid-work
[09:51:59 EDT(-0400)] * anastasiac (n=team@142.150.154.149) has joined #fluid-work
[09:54:33 EDT(-0400)] * EricDalquist (n=dalquist@bohemia.doit.wisc.edu) has joined #fluid-work
[10:02:55 EDT(-0400)] <theclown> anastasiac: is there book club today? where? when?
[10:06:44 EDT(-0400)] <anastasiac> don't know - not many people here
[10:54:13 EDT(-0400)] * jayshao (n=jayshao@pool-72-79-114-2.nwrknj.east.verizon.net) has joined #fluid-work
[10:56:30 EDT(-0400)] * colinclark (n=colin@bas1-toronto09-1279543729.dsl.bell.ca) has joined #fluid-work
[11:57:55 EDT(-0400)] * RayDavis (n=chatzill@dhcp-169-229-212-40.LIPS.Berkeley.EDU) has joined #fluid-work
[13:15:37 EDT(-0400)] * phiggins (n=dante@c-68-34-199-67.hsd1.tn.comcast.net) has joined #fluid-work
[13:36:49 EDT(-0400)] * colinclark (n=colin@bas1-toronto09-1279543729.dsl.bell.ca) has joined #fluid-work
[14:14:40 EDT(-0400)] * michelled (n=team@142.150.154.199) has joined #fluid-work
[14:44:10 EDT(-0400)] <colinclark> So a question about API documentation.
[14:44:40 EDT(-0400)] <colinclark> We haven't settled on a standard. Coming from a background in Java development, several of us have favoured JavaDoc style API documentation.
[14:45:06 EDT(-0400)] <anastasiac> I'm happy to write it any way
[14:45:08 EDT(-0400)] <colinclark> I have always found it a touch verbose, but it is familiar. JSDoc will parse this same format.
[14:45:11 EDT(-0400)] <colinclark> http://jsdoc.sourceforge.net/
[14:45:19 EDT(-0400)] <anastasiac> you beat me to my question 
[14:45:22 EDT(-0400)] <colinclark>
[14:45:26 EDT(-0400)] <EricDalquist> mmm javadocs
[14:45:51 EDT(-0400)] <colinclark> I don't know if there are other alternatives that are more JS-ish.
[14:46:03 EDT(-0400)] <anastasiac> ok, I'll look into the tool, and see if there's anything else
[14:46:12 EDT(-0400)] <colinclark> theclown: What do you guys do for API documentation in Dojo?
[14:46:15 EDT(-0400)] <michelled> does anyone know if jquery auto generates their docs? I like them.
[14:47:32 EDT(-0400)] <colinclark> I think they do have a certain amount of autogeneration, but I'd have to look into it. I was under the impression that this was how Visual jQuery and the like worked.
[14:49:19 EDT(-0400)] <colinclark> Looks like they use ScriptDoc: http://www.scriptdoc.org/specification.htm
[14:49:31 EDT(-0400)] <colinclark> Which looks an awful lot like JavaDoc.
[14:50:39 EDT(-0400)] <colinclark> Yet their trunk source code doesn't seem to show this. I'm confused.
[14:51:27 EDT(-0400)] <anastasiac> where did you see that they use scriptdoc?
[14:52:42 EDT(-0400)] <colinclark> In the make file.
[14:52:53 EDT(-0400)]
[14:52:54 EDT(-0400)]
[14:53:22 EDT(-0400)] <colinclark> Leopard doesn't ship with a copy of make installed by default!
[14:56:03 EDT(-0400)] <michelled> colinclark: I'm currently updating the html files and I noticed a recurring comment: "These are the required javascript modules for the Lightbox eventually to be replaced with a single build generated file"
[14:56:25 EDT(-0400)] <michelled> Does the build now generate a single file?
[14:57:17 EDT(-0400)] <EricDalquist> colinclark: that's probable a good thing, if it did it would probably be 1/2 broken like most other unixy tools on osx 
[14:57:38 EDT(-0400)] <EricDalquist> Use MacPorts ... I think I've replaced most of the common shell tools with ports already
[14:59:34 EDT(-0400)] <colinclark> EricDalquist: Yes, good point. I will.
[14:59:55 EDT(-0400)] <EricDalquist> I'm still completely baffeled at the un-functionality of find on OS X
[15:00:13 EDT(-0400)] <anastasiac> colinclark, FYI: Steve now has commit access to TransformAble
[15:00:22 EDT(-0400)] <colinclark> Great!
[15:00:30 EDT(-0400)] <colinclark> michelled: You should try it for yourself.
[15:00:38 EDT(-0400)] <colinclark> But yes, it builds a single file called Fluid-all.js
[15:01:16 EDT(-0400)] <michelled> ya, I should
[15:02:35 EDT(-0400)] <colinclark> I answered my own question about Dojo's documentation format.
[15:02:36 EDT(-0400)] <colinclark> http://dojotoolkit.org/forum/dojo-core-dojo-0-9/dojo-core-development-discussion/code-documentation-format
[15:02:39 EDT(-0400)] <colinclark> I will bite my tongue.
[15:04:13 EDT(-0400)] <michelled>
[15:07:15 EDT(-0400)] * jayshao (n=jayshao@pool-72-79-114-2.nwrknj.east.verizon.net) has joined #fluid-work
[15:07:51 EDT(-0400)] <colinclark> From cursory reading, ScriptDoc seems fairly sensible. http://www.scriptdoc.org/specification.htm
[15:14:41 EDT(-0400)] <anastasiac> am I reading it wrong, or is ScriptDoc just the specification, and not any actual tool?
[15:20:45 EDT(-0400)] <colinclark> There are tools for it.
[15:21:33 EDT(-0400)] <michelled> anyone see a problem with the tests depending on stuff in the markup examples directory?
[15:22:26 EDT(-0400)] <michelled> There is a lot of initialization javascript that is duplicated between the two and I think it makes sense to leave it in the markup examples and point to it from the tests
[15:24:19 EDT(-0400)] <michelled> colinclark: silence mean agreement 
[15:24:31 EDT(-0400)] <colinclark> Sorry, I was being productive.
[15:24:45 EDT(-0400)] <michelled> ya, stop that and chat with me instead
[15:25:17 EDT(-0400)] <colinclark> So the side effect is that tests would fail if the markup examples weren't around?
[15:25:23 EDT(-0400)] <michelled> yup
[15:25:42 EDT(-0400)] <colinclark> I think for now it makes sense. What kind of initialization code are we talking about?
[15:26:12 EDT(-0400)] <michelled> An example is the Scheduler-setup.js and Scheduler.js files. I think they are identical
[15:26:17 EDT(-0400)] * davidb (n=davidb@142.150.154.101) has joined #fluid-work
[15:26:37 EDT(-0400)] <colinclark> let me take a peek
[15:26:48 EDT(-0400)] <michelled> they have functions that create callbacks and finders etc and then create a Reorderer.
[15:27:34 EDT(-0400)] <colinclark> Oooh, ouch.
[15:27:36 EDT(-0400)] <michelled> Looking closer that is the biggest example of the duplication.
[15:27:52 EDT(-0400)] <colinclark> Someone needs their Apple C and Apple V keys removed.
[15:28:15 EDT(-0400)] <colinclark> Yes, I think it makes sense that the tests share with the examples.
[15:28:16 EDT(-0400)] <michelled> hey, it was a large change to move over to a new testing framework
[15:28:25 EDT(-0400)] <colinclark> I'm kidding. I understand.
[15:29:44 EDT(-0400)] <colinclark> You know, speaking of cutting and pasting, I am starting to miss the refactoring tools in Eclipse.
[15:29:52 EDT(-0400)] <colinclark> It's making me think about trying out Aptana again.
[15:30:29 EDT(-0400)] <michelled> It was pretty bad when we first started but that was a year ago. Let us know how your experiment goes if you switch.
[15:31:16 EDT(-0400)] <colinclark> Eli seems to love it. He's using a standalone version, so it's like a fully self-contained version of Eclipse.
[15:31:30 EDT(-0400)] <colinclark> davidb: Do you use a JS editor of any sort?
[15:31:45 EDT(-0400)] <davidb> colinclark: just the webby stuff eclipse comes with
[15:32:07 EDT(-0400)] <davidb> colinclark: i tried aptana about a yr ago. was nice... had some dojo nicies too.
[15:32:08 EDT(-0400)] <colinclark> I tried ATF and it showed promise but was horribly buggy.
[15:32:26 EDT(-0400)] <davidb> colinclark: try vim
[15:32:44 EDT(-0400)] <colinclark> JSEclipse is fine as a basic editor, but now that we Do The Right Thing and encapsulate our code in closures, its outline view is useless.
[15:32:50 EDT(-0400)] <colinclark> And Aptana was ad-ridden.
[15:33:02 EDT(-0400)] * davidb looks at his eclipse setup
[15:33:08 EDT(-0400)] <colinclark> But their pay product, Aptana Studio, looks pretty tempting.
[15:33:36 EDT(-0400)] <colinclark> davidb: anastasiac is a monster vim jockey.
[15:35:40 EDT(-0400)] <davidb> i use the javascript editor in eclipse... i can't remember if i did anything special to get it
[15:35:50 EDT(-0400)] <davidb> colinclark: ^
[15:35:59 EDT(-0400)] <EricDalquist> it just comes with the j2ee version of eclipse 3.3
[15:36:30 EDT(-0400)] <colinclark> davidb (or EricDalquist): Do you know if the outline view works with it?
[15:36:41 EDT(-0400)] <colinclark> Especially with code defined in closures?
[15:36:43 EDT(-0400)] <EricDalquist> nope, I don't do enough JS editing to notice
[15:37:21 EDT(-0400)] <davidb> i use WST (in eclipse) i think
[15:38:39 EDT(-0400)] <anastasiac> colinclark (or anyone else): regarding tools for ScriptDoc - do you know of any in particular? Maybe my google skills are lacking, but I'm not having any luck
[15:41:38 EDT(-0400)] <colinclark> anastasiac: Aptana will parse them.
[15:41:56 EDT(-0400)] <colinclark> But I'm having trouble figuring out others, since there's also confusing with a .NET product that used to be called ScriptDoc, too.
[15:43:40 EDT(-0400)] <colinclark> Luckily ScriptDoc and JSDoc are very close syntactically, and I'm only using very basic features. So it may not matter.
[15:43:42 EDT(-0400)] <colinclark> But good point.
[15:49:29 EDT(-0400)] <anastasiac> It looks like Aptana does not generate documentation i.e. no html or xml - it parses for its own internal use
[15:50:09 EDT(-0400)] <colinclark> Hmm.
[15:50:32 EDT(-0400)] <colinclark> It appears also that jQuery discontinued the use of ScriptDoc as of version 1.2 in favour of API documentation in the wiki.
[15:50:34 EDT(-0400)] <anastasiac> it's a planned feature
[15:51:11 EDT(-0400)] <colinclark> Which is a good point. I rarely use generated documentation. In fact the only ones I really loved were the WebObjects JavaDocs, because they were written by experienced technical writers.
[15:51:16 EDT(-0400)] <theclown> colinclark: sorry, I didn't see your question re: dojo docs, as I was sitting with davidb.
[15:51:23 EDT(-0400)] <theclown> now I'm back at my desk.
[15:51:27 EDT(-0400)] <colinclark> theclown: No problem, we figured it out.
[15:52:16 EDT(-0400)] <theclown> colinclark: okay. Since you figured it out, and I don't know the answer (I'm just learning the "style"), how do they do it? Or should I just look it up in the chat logs in the wiki?
[15:52:43 EDT(-0400)] <colinclark> You guys wrote your own: http://dojotoolkit.org/forum/dojo-core-dojo-0-9/dojo-core-development-discussion/code-documentation-format
[15:53:01 EDT(-0400)] <davidb> it is based on something (can't recall the name)
[15:53:15 EDT(-0400)] <colinclark> "You guys" being the inclusive term, now that you're also helping out on Dojo.
[15:53:31 EDT(-0400)] <davidb> you/we/ they what's the diff?
[15:53:35 EDT(-0400)] <davidb>
[15:53:39 EDT(-0400)] <theclown> exactly.
[15:53:52 EDT(-0400)] <colinclark> Indeed.
[15:54:00 EDT(-0400)] <theclown> forsooth
[15:54:21 EDT(-0400)] <anastasiac> so colinclark, are you changing your mind on generating api docs?
[15:54:39 EDT(-0400)] <colinclark> I was never interested in generating API docs.
[15:54:50 EDT(-0400)] <anastasiac> ah! I see...
[15:54:59 EDT(-0400)] <colinclark> Just in writing the occasional note on top of public APIs. In a standard format, preferably.
[15:55:18 EDT(-0400)] <davidb> dojo uses "Markdown" syntax for descriptions and code examples
[15:55:19 EDT(-0400)] <michelled> makes sense
[15:55:28 EDT(-0400)] <colinclark> I think our documentation and tutorials are a lot more effective at communicating usage than generated docs.
[15:55:33 EDT(-0400)] <theclown> Just in case it's useful, this appears to be the output for the dojo API docs:
[15:55:35 EDT(-0400)] <theclown> http://redesign.dojotoolkit.org/
[15:55:42 EDT(-0400)] <davidb> theclown: that's right
[15:55:49 EDT(-0400)] <colinclark> Thanks!
[15:56:00 EDT(-0400)] <theclown> it looks nice.
[15:56:13 EDT(-0400)] <davidb> what does jquery do?
[15:56:49 EDT(-0400)] * davidb wonders what js editor resig uses
[15:56:56 EDT(-0400)] <colinclark> davidb: They used to use ScriptDoc.
[15:57:06 EDT(-0400)] <theclown> I guess it's as good as the effort the author of the docs put into it (dojo api docs, that is)
[15:57:14 EDT(-0400)] <davidb> but no longer (colinclark)
[15:57:15 EDT(-0400)] <davidb> ?
[15:57:20 EDT(-0400)] <colinclark> That's where nice references tools like Visual jQuery came from. http://visualjquery.com/1.1.2.html
[15:57:29 EDT(-0400)] <davidb> yes i like that ref
[15:57:33 EDT(-0400)] <colinclark> But now they've moved API documentation into the wiki, where it can be collaborative.
[15:57:42 EDT(-0400)] <colinclark> That's why Visual jQuery is now out of date.
[15:57:48 EDT(-0400)] <davidb> colinclark: so not generated?
[15:57:51 EDT(-0400)] <anastasiac> cool!!
[15:57:56 EDT(-0400)] <davidb> anastasiac:
[15:58:04 EDT(-0400)] <colinclark> davidb: Generated by people.
[15:58:09 EDT(-0400)] <theclown> not very keyboard accessible (always finding something to complain about)
[15:58:11 EDT(-0400)] <davidb> right ok
[15:58:51 EDT(-0400)] <davidb> theclown: that's where we/you/they come in to educate the community
[15:59:05 EDT(-0400)] <colinclark> Forsooth.
[15:59:11 EDT(-0400)] * davidb slaps forhead
[15:59:12 EDT(-0400)] <theclown> excelsior!
[15:59:19 EDT(-0400)] * davidb shakes head
[16:01:01 EDT(-0400)] <colinclark> fluid-work is developing a lovely air of medieval custom.
[16:01:38 EDT(-0400)] <theclown> time to bring in my lute.
[16:02:13 EDT(-0400)] <colinclark> I love secular medieval music. We could bang out some nice lute tunes.
[16:02:22 EDT(-0400)] <anastasiac> I could bring in my sword
[16:02:41 EDT(-0400)] <colinclark> Ack! Now none of us will disagree with you!
[16:02:49 EDT(-0400)] <colinclark> Or you will skewer us!
[16:02:51 EDT(-0400)] <colinclark>
[16:02:57 EDT(-0400)] <theclown> i will, but I will first purchase a tank
[16:03:08 EDT(-0400)] * colinclark listens to the sound of Darcie's MacBook finally booting up.
[16:03:11 EDT(-0400)] <anastasiac> no skewering - they're called 'strikes'
[16:03:33 EDT(-0400)] <davidb> harpsicord anyone
[16:03:35 EDT(-0400)] <davidb> ?
[16:03:48 EDT(-0400)] <theclown> and you want to avoid critical strikes.
[16:03:58 EDT(-0400)] <davidb> GG is dead.
[16:04:23 EDT(-0400)] <davidb> or is that MERP?
[16:04:24 EDT(-0400)] <colinclark> I have a copy of Die Wohle-Temperierte Clavier played on harpsichord here. We could listen to it.
[16:04:37 EDT(-0400)] <theclown> davidb: thanks for the cue http://www.youtube.com/watch?v=4fZ8pTrmnkc
[16:05:29 EDT(-0400)] <theclown> prelude 
I (one) was a favourite.
[16:06:39 EDT(-0400)] <theclown> s/was/is
[17:03:52 EDT(-0400)] * theclown (n=theclown@142.150.154.101) has left #fluid-work
[17:07:40 EDT(-0400)] * whiteg (n=whiteg@67.211.202.225) has joined #fluid-work
[17:45:13 EDT(-0400)] * slightlyoff (n=alex@204.14.154.209) has joined #fluid-work
[20:11:21 EDT(-0400)] * colinclark (n=colin@bas1-toronto09-1279543729.dsl.bell.ca) has joined #fluid-work