Project status

Wed Aug 19 03:17:39 UTC 2015

On 19/08/2015 8:34am, Jonathan Gibbons wrote:

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

Thanks. That information isn't at all clear from Jira or from the project page. I notice that https://bugs.openjdk.java.net/browse/JDK-8042809 has Integration Due: 2015-08-14. Is that a date which isn't updated regularly with the current plan?

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

Ah right. So I'll need to check out and build the entire JDK rather than just be able to build the doclet library and test it? To avoid the time and setup of making a full build, would the best way to review your progress be to look at a download here:

https://jdk9.java.net/download/

Are new beta builds released once a week?

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

OK, great. But what about the public API for writing doclets? I'm guessing most of what exists today will go away (and good riddance since it is poorly documented and confusing). Is there any documentation of your goals in making it easy for developers to take the javadocs parser and produce very different resulting html (rather than just being able to tweak tiny edge cases)?

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

Well, not really just css. It does away with a lot of the problems in javadocs.

* remove the clumsy use of frames (bookmarkable documentation!)
* excessive repetition of boilerplate information on the page. The name of each method is listed at least three times in a javadoc page.
* remove "get" in getters (since groovy doesn't need them)

At any rate, to get to this point required completely abandoning javadoc and writing everything from scratch. Which is a shame.

But perhaps it is too late now in your project to be considering how people would like to use javadoc and it isn't working for them today. And maybe that's not the point of your project if the focus is just to use javax.lang.model as the new parser/model driving javadocs.

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

Is that part of this JEP or some future work? Ideally, it would be nice to provide two or three sample 'skins' for developers to drop in. These would just be additional css files which override parts of the base.css. Users can use those additional CSS files to use as examples for how to write their own customisations.

At any rate, I've been successful in hacking the css of the Java 8 docs without much trouble: http://www.ish.com.au/s/onCourse/doc/latest/api/  Going beyond that to changing the content with doclets has been really hard and I'm considering going the gradle way with writing the whole thing from scratch.

Cheers
Ari

-- 
-------------------------->
Aristedes Maniatis
ish
http://www.ish.com.au
Level 1, 30 Wilson Street Newtown 2042 Australia
phone +61 2 9550 5001   fax +61 2 9550 4001
GPG fingerprint CBFB 84B4 738D 4E87 5E5C  5EFA EF6A 7D2E 3E49 102A