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 14:01:02 -0700
From: "David W. Van Couvering" <David.Vancouvering@Sun.COM>
Subject: Re: Javadoc lies
In-reply-to: <44527CCF.90008@sun.com>
Sender: David.Vancouvering@Sun.COM
To: derby-dev@db.apache.org
Message-id: <4452828E.7050808@sun.com>
MIME-version: 1.0
Content-type: text/plain; format=flowed; charset=ISO-8859-1
Content-transfer-encoding: 7BIT
References: <44527CCF.90008@sun.com>
User-Agent: Thunderbird 1.5.0.2 (Windows/20060308)

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.

David

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
> 
>