db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rick Hillegas <Richard.Hille...@Sun.COM>
Subject Re: Javadoc lies
Date Fri, 05 May 2006 22:28:35 GMT
Thanks to everyone who responded to this thread. It doesn't seem that 
anyone has a solution to this problem. Does anyone have a preference for 
which lie we tell: (1b) or (2d)? Barring a preference here, the default 
would be (1b), our current behavior.


Rick Hillegas wrote:

> Right now the javadoc generated for jdk1.6 is telling a shocking lie. 
> I can fix this but only by inducing javadoc to tell a different lie. I 
> would like advice on how to get javadoc to tell the truth, the whole 
> truth, and nothing but the truth. If that's not possible, I'd like to 
> know which lie the community prefers.
> 1) How it is today.
> Right now, if you point your ant.properties at a 1.6 installation, we 
> build javadoc with the 1.6 javadoc tool. The tool assumes that you 
> built your whole classtree against 1.6 and that the compiler therefore 
> caught certain kinds of errors. In particular, if a class successfully 
> compiles under jdk1.4 against the jdk1.4 version of an interface, then 
> the 1.6 javadoc tool assumes that the class implements additional 
> methods added to that interface in jdk1.6. Here's an example of the 
> problems this causes:
> a) EmbeddedDataSource, compiled under jdk1.4, implements the 1.4 
> version of javax.sql.DataSource
> b) The 1.6 javadoc falsely says that EmbeddedDataSource implements the 
> Wrapper methods added to javax.sql.DataSource by jdk1.6
> 2) A possible fix and its countervailing lie
> It would be possible to use the 1.4 javadoc tool to build javadoc for 
> all the classes compiled under 1.4. Then we could use the 1.6 compiler 
> to build the whole classtree again. With a little jiggery-pokery, we 
> might be able to copy the additional javadoc html into the 1.4 javadoc 
> tree and use the 1.6 index.html to zipper the two trees together. Mind 
> you, I haven't built this yet, I'm just waving my hands. For the 
> example case above, we would end up with something like the following:
> c) EmbeddedDataSource would NOT assert that it implements the jdk1.6 
> Wrapper methods
> d) However, now EmbeddedDataSource would fail to say that it has an 
> important subclass, EmbeddedDataSource40
> 3) Other solutions?
> Does anyone have a better solution? Better means easier and/or more 
> truthful.
> 4) Lies and the lying liars who like them
> If not, which lie do you prefer: (1b) or (2d).
> Thanks,
> -Rick

View raw message