Hi David, I must humbly disagree. Maybe I just don't see enough Open Source projects, but MySQL, which I use on a regular basis, has documentation that is easy to search, has it all in one place, and does a good job of explaining what's going on.
The GWT documentation, OTOH, in my experience NEVER gives you a COMPLETE explanation on how to do anything. Which I find very frustrating, especially since I assume that, before you folks claim to have created a feature, you've actually TESTED that feature, which means that somewhere you must have the code that works out that feature to its fullest extent. Given that it's an open source project, I honestly fail to see why you wouldn't make that test code publicly available. But if you have, I can't find it anywhere. Take the CellTable for example. Clearly the purpose of the thing is to have something that lets you download chunks of data from a server, and display it quickly. So, what do all the "examples for how to use a CellTable" show? How to display local data. Is there ANYONE, ANYWHERE, who's going to use it for that purpose in an actual GWT application? So why is that the "example"? Presumably someone's actually written a GWT app that gets information from a servlet using RPC. Where is that code? Or, take a really frustrating case, because it was SO close to being great documentation. You've got a nice code sample at http://code.google.com/webtoolkit/doc/latest/DevGuideCodingBasicsHistory.html You've got an entirely different one in the history JavaDoc. Any reason why they couldn't be combined in one example, that includes the sample versions of addSelectionHandler and addValueChangeHandler that the JavaDoc lack, AND includes the rather vital History.fireCurrentHistoryState (); that the "Coding Basics" lack? Personally, if I were writing things for an open source project, it would be because I actually wanted people to use the things I was writing. So what's the point of writing great code if the documentation is so poor that few people can figure out how to use it? As for adding things to the project, there's a couple of problems with that: 1: The places where I want something added to the documentation are places where I don't know what the heck is going on. So I'd be the last person to add it. 2: My contract specifies that everything I write belongs to the people paying me. So I can't take the code I've written and add it to the GWT code base / documentation, because I lack the rights to it. 3: I'm working 50 hours a week writing code. By the time I get home, I lack the mental energy necessary to write code for any purpose. If you want to email me off list with a simple way to update the JavaDocs with what I've learned and think I can legally offer, there's some things I'd be happy to update. But the key word there is SIMPLE. If it requires jumping through a lot of hoops, then I've got much better things to do with my time. Respectfully, Greg On Dec 3, 2:05 pm, David Chandler <[email protected]> wrote: > Hi Greg, > > Prior to joining Google, I thought (and still do think) that the GWT > developer guides are actually pretty rich for an open source project and > many of the Javadocs, too. Of course, there are always holes and we welcome > constructive feedback through the issue tracker. > > GWT is open source, so I hope you will contribute Javadocs as you find > things that can be improved. > > /dmc > > 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. > > -- > David Chandler > Developer Programs Engineer, Google Web > Toolkithttp://googlewebtoolkit.blogspot.com/ -- 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.
