db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "David W. Van Couvering" <David.Vancouver...@Sun.COM>
Subject Re: Javadoc lies
Date Fri, 28 Apr 2006 21:01:02 GMT
It seems to me the real problem is that the way we compile source and 
the way we compile javadoc are inconsistent.

With that in mind, I have two thoughts, with no backing in understanding 
how things really work...

1) Fix javadoc compilation to be in line with source compilation: build 
it with two different versions of javadoc depending upon the source 
being javadoc'd.

2) Fix our source compilation to be consistent with javadoc -- that is, 
build everything with jdk 1.6.  I thought we had looked at doing this 
using the option that indicates that the target is 1.4.

Again, I am woefully short of facts, but they were two ideas I thought 
I'd put out there to see if they might help.


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