Javadoc lies

[Rick Hillegas <Ri...@Sun.COM>]

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

Re: Javadoc lies

[Rick Hillegas <Ri...@Sun.COM>]

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.

Regards,
-Rick

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

Re: Javadoc lies

["David W. Van Couvering" <Da...@Sun.COM>]

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

Re: Javadoc lies

[Andrew McIntyre <mc...@gmail.com>]

On 5/5/06, Rick Hillegas <Ri...@sun.com> wrote:
> 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.

Sorry for the late reply, I've been meaning to follow up on this. 1b
seems worse to me than 2d, but implementing 2d seems like a lot of
trouble to still have lies. For 2d, though, it seems like it would be
sufficient to mention that EmbeddedDataSource40 is actually a subclass
and then link to it.

As for 3 all I could think of was 3a) creating a doclet based on the
standard doclet with an overridden MethodDoc that ignores methods that
are @since 1.6 if the class version of the class containing the method
is < 1.6. Not sure how much work that is, but it might be fairly
involved. A less accurate but easier way of dealing with it would be
3b) (if you go with 1b) write a custom taglet that lets you mark
methods as not really implemented in this version of the class.

As for 4, well, unless anybody works on the other suggestions, looks
like we get 1b. :-)

andrew

Re: Javadoc lies

[Rick Hillegas <Ri...@Sun.COM>]

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