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, 28 Apr 2006 21:12:10 GMT
Thanks, David. I think that your suggestion (1) is pretty much what I 
intend by item (2) in my email. Under this solution I don't see how we 
coax javadoc into reporting that EmbeddedDataSource has a 1.6 subclass, 
EmbeddedDataSource40. Sigh.


David W. Van Couvering wrote:

> 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

View raw message