db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Craig L Russell <Craig.Russ...@Sun.COM>
Subject Re: Javadoc lies
Date Mon, 08 May 2006 16:15:02 GMT
Hi Rick,

On May 8, 2006, at 6:43 AM, Rick Hillegas wrote:

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

It sounds good to me. While it is a bit inconvenient having to  
specify at the "bolted web page" which API you're interested in, I  
think it's better than finding out the hard way that the javadoc info  
is incorrect.

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

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