javadoc and API docs

[Jonathan Gibbons]

On 03/26/2012 02:01 PM, Fredrik Öhrström wrote:
> 2012-03-26 13:34, Jonathan Gibbons skrev:
>> Right now, in the current build, we use a "hybrid" javadoc to build 
>> the API documentation, where "hybrid" means: latest sources, running 
>> on bootstrap JDK.
>>
>> Looking to the future, at least for Jigsaw, and now maybe for JSR 
>> 308, we may need to run javadoc on the newly built JDK.  Does anyone 
>> see any problems with doing that?
>>
>> -- Jon
>
> It seems counter intuitive that, something as trivial, as extracting 
> documentation
> from source files, should require the entire new jdk.... You need to 
> give us more
> information Jon.  Why can't we build a bootstrap javadoc that knows 
> how to deal
> with the new jdk sources (modules, type annotations et al)
> in the same way that we can build a bootstrap javac?
>
> //Fredrik

Fredrik,

There is a proposed API change for JDK 8, in 
java.lang.annotation.ElementType,
that would be appropriate to use in the javadoc standard doclet.

I would say the flip side is that it is counter-intuitive that we can't 
use the new
JDK. It is one thing to constrain javac to running on the bootstrap JDK; 
the more
we have to constrain additional tools, the more inconvenient it is.

The problem comes with the in-between API that lives in rt.jar but which 
is used
by the tools.

-- Jon