Project status

[Jonathan Gibbons]

The new Doclet impl in the javadoc-next/new-api is not yet stable, 
although it is Jolly Good. That's an official British technical term :-)

It may be possible to backport it to 8 and 7, but that may not be a 
trivial amount of work.  In particular, the doclet supports type 
annotations (new in 8) and relies on bug fixes in javac found in 9.

-- Jon


On 08/18/2015 04:37 PM, Kaz Nishimura wrote:
> How stable is the new Doclet implementation? I would like to backport it to
> JDK 8 and, if possible, to 7.
>
> 2015年8月19日(水) 7:34 Jonathan Gibbons <jonathan.gibbons at oracle.com>:
>
>>
>> On 08/17/2015 01:54 AM, Aristedes Maniatis wrote:
>>> I notice that conversation around this project is being conducted
>> largely in private rather than on this mailing list. I found
>> http://hg.openjdk.java.net/javadoc-next however no clue about where to
>> start or how to build this project and test it.
>>> Do you have any information about:
>>>
>>> * when will a decision be made about whether it makes the java 9 cut?
>> The project page[1] lists various features being considered.  You can
>> follow the links to see more details on the individual JEPs.
>> HTML 5: has been completed and is already in JDK 9
>> Simplified Doclet API: is "Targeted" for 9, and will be integrated when
>> the implementation is further along.
>> Search capabilities: is "Proposed to Target", which means it is still a
>> work in progress.
>>
>>
>>
>>> * how can I utilise and test what's been done already to see how it fits
>> my needs? How do I build it?
>>
>> You can access the HTML 5 features in the JDK 9 forest. [2]
>> The new API work is incubating in the javadoc-next/new-api forest [3]
>>
>> These are standard OpenJDK forests which you can build in the standard way.
>>
>>> * Do you have nightly CI runs with compiled output? Will they run on
>> Java 8 or do they require the latest Java 9 beta?
>>
>> These features will all be part of JDK 9, and will generally require JDK
>> 9 on which to run.
>>
>>> * where do I find a set of detailed project goals and community feedback
>> about the API design decisions?
>>
>> The API design goals in the "Simplified Doclet API" are outlined in the
>> JEP. The design that ensues is largely a case of removing the original
>> com.sun.javadoc API and replacing it with use of the existing
>> javax.lang.model and com.sun.source APIs.
>>
>>
>>> I'm looking to write some glue between the new javadoc API and docbook,
>> in order provide a richer output. You can see the absolutely lovely API
>> documentation the gradle project achieved here:
>>>     https://docs.gradle.org/current/dsl/
>>>
>>> but that was only by completely bypassing Javadoc and writing their own
>> class parsers, docbook integration and styling. Effectively it takes all
>> the javadoc html content, converts it to docbook, adds a layer of docs and
>> styling, then converts it back to html/pdf. I'm looking at something
>> similar but your new API might offer a simpler approach.
>>
>> I agree your gradle docs look absolutely lovely, but it does seem to be
>> "Just like Javadoc output, with different styles". Another feature we
>> would like to address is to make it easier for users to restyle the
>> standard javadoc output for themselves. It is already the case that you
>> can provide your own stylesheet, but currently the names and usage of
>> the styles contained in the stylesheet is not well defined and that
>> needs to be fixed.
>>
>>>
>>>
>>> Thanks
>>>
>>> Ari Maniatis
>>>
>>>
>>>
>> -- Jon Gibbons
>>
>> [1] http://openjdk.java.net/projects/javadoc-next/
>> [2] http://hg.openjdk.java.net/jdk9/jdk9/
>> [3] http://hg.openjdk.java.net/javadoc-next/new-api/
>>