harmony-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Dalibor Topic <robi...@kaffe.org>
Subject Re: Writing JavaDoc
Date Tue, 10 Jan 2006 15:08:36 GMT
Tim Ellison wrote:
> Sorry, I misunderstood.  So your option #3 is not copying the JavaDoc
> and redistributing it, but documenting links to the Sun site.
> 
> IMHO, creating a set of JavaDoc that contains links to Sun's existing
> JavaDoc is unlikely to appeal to most people -- the package/type/method
> naming is enough of an index to go and find it easily on the Sun website
> already.  Publishing an index of links doesn't add anything.
> 

+1

> If the additional 'value' are the comments that are added, then I expect
> that annotating Sun's original JavaDoc may be frowned upon(*).  At least
> if we originally author all the documentation we can do what we like.
> 

Indeed. The license of the specs would not really allow annotation
anyhow, I believe.

> I'm interested to hear others' views.

Writing one's own JavaDocs to document the behaviour of the code (rather
then rewriting the specs) would seem to me to be preferable, i.e. option
2, with a different goal. There are some implementation-dependant parts
of J2SE which require documenting the actual behaviour of the
implementation to be useful.

I'd find it more interesting that trying to rewrite specs to see formal
specifications of J2SE APIs integrated with the implementation. But that
could suffer from a long term maintainance problem if it was not part of
a JCP effort. And if it was, it would not be free, so it would not
really be useful. Catch 22. :)

cheers,
dalibor topic

Mime
View raw message