Mailing-List: contact derby-dev-help@db.apache.org; run by ezmlm
Precedence: bulk
Reply-To: <derby-dev@db.apache.org>
Received-SPF: pass (asf.osuosl.org: local policy)
Date: Fri, 28 Apr 2006 13:36:31 -0700
From: Rick Hillegas <Richard.Hillegas@Sun.COM>
Subject: Javadoc lies
Sender: Richard.Hillegas@Sun.COM
To: Derby Development <derby-dev@db.apache.org>
Message-id: <44527CCF.90008@sun.com>
MIME-version: 1.0
Content-type: text/plain; format=flowed; charset=ISO-8859-1
Content-transfer-encoding: 7BIT
User-Agent: Mozilla Thunderbird 1.0.6 (Windows/20050716)

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