Jeff, My point is, why isn't that stuff in the JavaDoc? "Assigns a Handler for a KeyPressEvent. It is fired, once, whenever a key is pressed down and then released." With, perhaps, a link to the W3C definition of a KeyPress.
The person writing that code needs to know that, yes? And probably has that link to the W3C definition sitting there while writing the code. So, instead of making users go hunt that down, why not make the documentation actually useful, and include it? I'm trying to find a way to say this that doesn't come across as sarcastic, rude, or hostile, so if I fail at that, you have my apologies in advance: I can understand if a bunch of Google and other engineers working on a web application toolkit think that reading W3C documents is a valuable way to spend their time, but most of the rest of us don't feel that way. I've got lots of interesting problems to solve, and none of them involve anything from the W3C (my current project involves taking a 100+ column, 130,000+ row spreadsheet, and turning the data in that spreadsheet into information that a human being can understand and use). I'm using GWT so that I can focus on the problems I find interesting, and leave the W3C crap to people who find THAT interesting. If you're writing a piece of code for other people to use, then the job's not done until you've documented the code well enough so that other people actually CAN use it. If you can't explain what it is your routine does, and why a user should want to use it, then you don't understand it yourself, and shouldn't be writing it. If you WON'T explain that, I seriously don't understand why you're writing it in the first place. Greg On Dec 4, 8:19 am, Jeff Schwartz <[email protected]> wrote: > You are welcome, Greg. In the future, whenever you are unsure about an event > type, check the documentation out at W3C's site for a starter as many GWT > events map 1 to 1 to DOM javascript events. By reading up on the javascript > event it will shed light on the GWT side of things. There are other sites as > well besides the W3C but I always hit them first because they are the > standards body. > > Jeff > > On Fri, Dec 3, 2010 at 2:50 PM, Greg Dougherty > <[email protected]>wrote: > > > > > Jeff, > > > Thank you. That' lets me know which one I want to use. > > > If I knew JavaScript and DOM, or, for that matter, even WANTED to know > > JavaScript and DOM, I wouldn't be using GWT, I'd be writing the > > JavaScript myself. No? > > > The whole point of using something like GWT is that it lets a Java > > programmer write a web app w/o having to learn all the crap that > > normal web app writers have to wade through. That's certainly why I > > spent the time and effort to learn GWT. For that matter, I presume > > that the people writing things like the KeyPressEventHandler DO know > > JavaScript and DOM. So, really, how hard is it for them to put that > > knowledge into the documentation? Isn't that what the documentation > > is THERE for? > > > I write a JavaDoc header for every routine I write. And the point of > > that header is to explain why it is that someone would be calling that > > routine, and what they'll get by calling it. To my mind that's the > > MINIMUM that should be in any JavaDoc, and if you're not going to > > cover that, you should stop wasting time and just not write anything. > > Do you disagree? > > > What % of the GWT JavaDoc actually answer those questions? 1%? 10%? > > > Greg > > > On Dec 3, 1:09 pm, Jeff Schwartz <[email protected]> wrote: > > > KeyPress - triggered when the user presses a key and releases it (key > > down > > > and then key up) > > > KeyDown - triggered when the user presses the key (key down) > > > > Perhaps the documentation assumes some prior knowledge of javascript and > > dom > > > events and though GWT tries to shield the developer from much of it it > > > cannot do so 100%. > > > > Jeff > > > > On Fri, Dec 3, 2010 at 1:47 PM, Greg Dougherty > > > <[email protected]>wrote: > > > > > This is my first entry in what will be a continuing series of pointing > > > > out GWT JavaDocs achieving Microsoftian levels of "saying everything > > > > while explaining nothing." Why? Because if you're going to actually > > > > write documentation, it shouldn't be totally worthless. > > > > > KeyPressHandler: Handler interface for KeyPressEvent events > > > > KeyDownHandler: Handler interface for KeyDownEvent events > > > > > KeyPressEvent : Represents a native key press event > > > > KeyDownEvent: Represents a native key down event > > > > > Does anyone believe this "documentation" provides anything of value? > > > > I sure don't. What I want to know is what is teh difference between > > > > these two things? What, EXACTLY, is a KeyDownEvent? How does it > > > > differ from KeyPressEvent ? When would I use one, when would I use > > > > the other? Which one should I use if I want to fire off a command > > > > when the user hits Enter or Return? > > > > > The first place most people are going to look to answer these > > > > questions is the JavaDoc. If you're programming in Eclipse (and, if > > > > you're not, you're wasting a lot of time and killing your > > > > productivity), you get the JavaDoc whenever you hover over one of > > > > these objects, which means that the fist place to put anything and > > > > everything the user needs to know is there (you want to put it other > > > > places, too? Great. Disk space is cheap. Programmer time is not). > > > > > So, what IS the difference between the two? Anyone know? Because > > > > while I could make a guess, I'm not paid to guess, I'm paid to know. > > > > (And yes, I'd be quite happy to pay ~$50 to get JavaDoc for GWT that > > > > were something more than the pointless repeating of what's already > > > > there. Anyone selling something like that for GWT 2.1?) > > > > > -- > > > > You received this message because you are subscribed to the Google > > Groups > > > > "Google Web Toolkit" group. > > > > To post to this group, send email to > > [email protected]. > > > > To unsubscribe from this group, send email to > > > > [email protected]<google-web-toolkit%[email protected]> > > <google-web-toolkit%[email protected]<google-web-toolkit%[email protected]> > > > > > . > > > > For more options, visit this group at > > > >http://groups.google.com/group/google-web-toolkit?hl=en. > > > > -- > > > *Jeff Schwartz* > > > -- > > You received this message because you are subscribed to the Google Groups > > "Google Web Toolkit" group. > > To post to this group, send email to [email protected]. > > To unsubscribe from this group, send email to > > [email protected]<google-web-toolkit%[email protected]> > > . > > For more options, visit this group at > >http://groups.google.com/group/google-web-toolkit?hl=en. > > -- > *Jeff Schwartz* -- You received this message because you are subscribed to the Google Groups "Google Web Toolkit" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/google-web-toolkit?hl=en.
