harmony-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Tim Ellison <t.p.elli...@gmail.com>
Subject Re: Dalvik's Javadoc
Date Fri, 28 May 2010 08:54:59 GMT
On 28/May/2010 00:23, Jesse Wilson wrote:
> On Thu, May 27, 2010 at 4:04 PM, Joshua Bloch <jjb@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


Mime
View raw message