harmony-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From enh <...@google.com>
Subject Re: Dalvik's Javadoc
Date Fri, 28 May 2010 15:33:39 GMT
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.ellison@gmail.com> wrote:
> 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
>
>



-- 
Elliott Hughes - http://who/enh - http://jessies.org/~enh/

Mime
View raw message