indeed. or as we've been saying "tutorial versus quick reference versus specification". i've been erring in favor of "quick reference": aiming at people who know what they're doing, but need their memory jogged.
the other thing i consider important, which i think Sun was always very bad at, is going out of our way to point out gotchas, and going out of our way to cross-reference related API and give explicit advice on how to choose between the alternatives. i wish we had the likes of Josh, Elliotte Rusty-Harold, and Cay Horstmann contributing --- their books epitomize the kind of thing i'd most like to see in the Android/Crore library documentation. practical advice for the working programmer that considers the trade-offs, written by people who've _used_ the stuff, rather than just implemented it because their manager told them so, using a design they aren't even aware isn't very good. (but i'll +2 just about anything that isn't wrong or misleading, so any time anyone's thinking of blogging about a class or method that's tripped them up, feel free to contribute some quality documentation!) --elliott On Fri, May 28, 2010 at 01:54, Tim Ellison <t.p.elli...@gmail.com> wrote: > On 28/May/2010 00:23, Jesse Wilson wrote: >> On Thu, May 27, 2010 at 4:04 PM, Joshua Bloch <j...@google.com> wrote: >> >>> I was a bit surprised to see efforts being made to improve Android docs. >>> The previous common wisdom had been "ignore them; everyone with any sense >>> will read JDK JavaDocs instead." >> >> >> The new goal of our team is, "write better docs than the originals". This is >> ambitious and will take a long, long time. But there are already a few >> places where we've beaten the JDK. Embedded reference-guide docs like >> Formatter<https://android-git.corp.google.com/w/?p=platform/libcore.git;a=blob;f=luni/src/main/java/java/util/Formatter.java;h=7000581739dfae57f089036739b51f7acf8f7eea;hb=dalvik-dev>and >> Pattern<https://android-git.corp.google.com/w/?p=platform/libcore.git;a=blob;f=luni/src/main/java/java/util/regex/Pattern.java;h=7733b729241d315d60878a3518822d95f6908de1;hb=dalvik-dev>are >> now better organized and more task-oriented than the Sun docs. Bogus >> APIs like >> InflaterInputStream.available()<https://android-git.corp.google.com/w/?p=platform/libcore.git;a=blob;f=luni/src/main/java/java/util/zip/InflaterInputStream.java;h=2243e77b5547bb401f895f4e727b8028e331a68a;hb=dalvik-dev>document >> why they're broken rather than sweeping their problems under the >> rug. >> >> We have a slight advantage over Oracle on writing these docs because we're >> not afraid to point out mistakes. > > It's always struck me that JavaDoc is trying to serve multiple purposes, > and falls short on each one of them. > > (a) It is a narrative on the design of the Package/Class/Method so > developers understand the purpose for this part of the library. > > (b) It is a specification, detailing the formal parameter constraints etc. > > (c) It often has snippets of sample code showing how it is used. > > Different areas of the class libraries seem to emphasize different > aspects, and different JSR authors have different styles, so you end up > with a real mix. > > All of those uses for class library documentation are valid. It would > be useful to distinguish the readers' objectives explicitly so that > authors address those needs specifically. > > The closest I've seen to this is the jDocs.com site that presents a spec > / code / books / wiki view across the APIs. > > Regards, > Tim > > -- Elliott Hughes - http://who/enh - http://jessies.org/~enh/
