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.
