db-derby-user 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 Mon, 08 May 2006 13:43:04 GMT
Thanks to Andrew, Craig, and David for your responses.

I agree with Andrew that writing custom doclets sounds like a lot of 
tricky work.

I like Craig's suggestion that we ship two sets of public javadoc, a 
JDBC3 javadoc for users who run on jdk1.3-1.5 and a JDBC4 javadoc for 
users who run on jdk1.6. We could prune irrelevant classes from each 
set. Besides solving the immediate problem, this approach would be less 
confuing. Right now the composite javadoc, which contains both the JDBC3 
and JDBC4 apis mixed together, is puzzling. Craig's solution would look 
like this:

i) We would generate the JDBC3 api using the 1.4 javadoc tool. The 
missing subclass references shouldn't confuse customers because the 
subclasses wouldn't appear in the JDBC3 api.

ii) We would generate the JDBC4 api using the 1.6 javadoc tool. This api 
would not contain the lying classes from the JDBC3 api.

iii) We would bolt a webpage on top of the top apis, explaining which 
api to consult, based on the client VM.

Does this sound acceptable?

Thanks,
-Rick

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