db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Van Couvering <David.Vancouver...@Sun.COM>
Subject Re: Javadoc lies
Date Sat, 06 May 2006 04:05:29 GMT
+1, I like this better than having inaccurate javadocs.

Craig L Russell wrote:
> Hi Rick,
> 
> I'm intentionally cross-posting to derby-user just because lies in 
> javadoc are supposed to affect users, not only developers.
> 
> How about:
> 
> 3. Build two sets of javadoc, one using jdk 1.4 and another using 1.6. 
> Distribute both sets of javadoc. Require the user to choose which 
> javadoc to use based on which jvm she chooses to run. Tell no lies.
> 
> I'm sure I'm missing something; hopefully it's not obvious. :-)
> 
> Craig
> 
> 
>> 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.
>>
>> Thanks,
>> -Rick
>>
>> 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
>>
> Craig Russell
> 
> Architect, Sun Java Enterprise System http://java.sun.com/products/jdo
> 
> 408 276-5638 mailto:Craig.Russell@sun.com
> 
> P.S. A good JDO? O, Gasp!
> 
> 

Mime
View raw message