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
