javadoc JDK 8 build dependency

[Jonathan Gibbons]

Werner,
> Dr. Egon Spengler: There's something very important I forgot to tell you.
> Dr. Peter Venkman: What?
> Dr. Egon Spengler: Don't cross the streams.
> Dr. Peter Venkman: Why?
> Dr. Egon Spengler: It would be bad.
> Dr. Peter Venkman: I'm fuzzy on the whole good/bad thing. What do you 
> mean, "bad"?
> Dr. Egon Spengler: Try to imagine all life as you know it stopping 
> instantaneously and every molecule in your body exploding at the speed 
> of light.
> Dr Ray Stantz: Total protonic reversal.
> Dr. Peter Venkman: Right. That's bad. Okay. All right. Important 
> safety tip. Thanks, Egon.


So what you're doing with your edit is mixing the runtime-world and 
compile-time world, and the preceding quote should give you a reasonable 
idea of Hollywood's visualization of the consequences if and when they 
get around to making "The JSR 308 Story". :-)

Bottom line, don't use java.lang.annotation.ElementType, since javadoc 
may not be running in a context where it is available.

As best I can tell, you need an enum with three values, METHOD, 
PARAMETER, and TYPE_USE, to disambiguate where javadoc finds an 
annotation.  Just as the compile-time reflective view of the world in 
javax.lang.model is a dual of the runtime reflection view of the world 
in java.lang, java.lang.reflect, and java.lang.annotations, so you 
should be looking for an enum in javax.lang.model with the values you 
want. ElementKind is the compile-time equivalent of ElementType, but 
ElementKind does not have the new value ElementType.TYPE_USE.  I guess 
you could discuss that with Joe Mr javax.lang.model Darcy, but in the 
meantime, you might consider using a private new enum declared within 
javadoc for its own internal use.

-- Jon







On 05/08/2012 11:10 PM, Werner Dietl wrote:
> Jon,
>
>> Can you point out where you are using reflection to work around the
>> compile-time issue?
> In com.sun.tools.doclets.internal.toolkit.util.Util I added method
> getElementTypeTypeUse() that uses
>
> ElementType.valueOf("TYPE_USE")
>
> instead of direct accesses to the new TYPE_USE constant.
> (Does this qualify as reflection? Maybe there is a better term for
> accessing an enum constant like this?)
>
> Using this method allows the bootstrap compilation of langtools, but
> then when the jdk build uses javadoc, we need to ensure that the
> TYPE_USE enum constant is actually there.
> I recently pushed this change to the jdk build file and the forest now
> builds correctly for me:
>
> http://buffalo.cs.washington.edu:8080/job/type-annotations/lastBuild/console
>
> Do let me know whether you see a different fix for this issue.
>
> Best regards,
> cu, WMD.
>
>
>> On 04/30/2012 10:21 PM, Werner Dietl wrote:
>>> Dear fellow type annotations developers,
>>>
>>> currently building the JDK documentation fails, because javadoc now
>>> uses the ElementTypes.TYPE_USE field. We prevent the static compile
>>> error by looking up the field via reflection; however, we also need to
>>> adapt the classpath at execution time to use the correct version of
>>> ElementTypes.
>>> I propose the following simple change:
>>>
>>>
>>> diff --git a/make/common/shared/Defs-java.gmk
>>> b/make/common/shared/Defs-java.gmk
>>> --- a/make/common/shared/Defs-java.gmk
>>> +++ b/make/common/shared/Defs-java.gmk
>>> @@ -178,7 +178,7 @@
>>>
>>>   "-Xbootclasspath/p:$(JAVAH_JAR)$(CLASSPATH_SEPARATOR)$(JAVAC_JAR)"  \
>>>                 -jar $(JAVAH_JAR) $(JAVAHFLAGS)
>>>     JAVADOC_CMD = $(BOOT_JAVA_CMD) \
>>> -
>>> "-Xbootclasspath/p:$(JAVADOC_JAR)$(CLASSPATH_SEPARATOR)$(JAVAC_JAR)$(CLASSPATH_SEPARATOR)$(DOCLETS_JAR)"
>>> \
>>> +
>>> "-Xbootclasspath/p:$(CLASSBINDIR)$(CLASSPATH_SEPARATOR)$(JAVADOC_JAR)$(CLASSPATH_SEPARATOR)$(JAVAC_JAR)$(CLASSPATH_SEPARATOR)$(DOCLETS_JAR)"
>>> \
>>>                 -jar $(JAVADOC_JAR) $(JAVADOCFLAGS)
>>>   else
>>>     # If no explicit tools, use boot tools (add VM flags in this case)
>>>
>>>
>>> Please do let me know if you're not running into this build problem
>>> and I'll investigate my setup.
>>> Is this an acceptable additional build dependency?
>>> Could you update me on the build status on the Oracle servers?
>>>
>>> Thanks and best regards,
>>> cu, WMD.
>>>
>
>