Project status

Wed Aug 19 07:47:23 UTC 2015

Hi,

just had a look at the latest javadoc here:

http://download.java.net/jdk9/docs/api/index.html

Is this the new HTML5 version?

There are still frames - will we get rid of them?

What about the representation of the "module" context from jigsaw in the
javadoc? Will this be visible somehow? Else you will never know where a
class belongs to...

Thanks

Sven

On Wed, Aug 19, 2015 at 5:17 AM, Aristedes Maniatis <ari at ish.com.au> wrote:

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

-- 
Sven Reimers

* Senior Expert Software Architect
* Java Champion
* NetBeans Dream Team Member: http://dreamteam.netbeans.org
* Community Leader  NetBeans: http://community.java.net/netbeans
                              Desktop Java:
http://community.java.net/javadesktop
* JUG Leader JUG Bodensee: http://www.jug-bodensee.de
* Duke's Choice Award Winner 2009
* Blog: https://www.java.net//blog/sven

* XING: https://www.xing.com/profile/Sven_Reimers8
* LinkedIn: http://www.linkedin.com/in/svenreimers

Join the NetBeans Groups:
* XING: http://www.xing.com/group-20148.82db20
* NUGM: http://haug-server.dyndns.org/display/NUGM/Home
* LinkedIn: http://www.linkedin.com/groups?gid=1860468
                   http://www.linkedin.com/groups?gid=107402
                   http://www.linkedin.com/groups?gid=1684717
* Oracle: https://mix.oracle.com/groups/18497