Project status
Jonathan Gibbons
jonathan.gibbons at oracle.com
Wed Aug 19 19:21:20 UTC 2015
The generated output for the platform output is still using HTML 4.
The "HTML 5" support that I referred to is the ability of javadoc to
generate HTML5 compliant output, when enabled by the appropriate new
option (-html5). We have not yet enabled the feature when we generate
the platform documentation, because some of the doc comments in the Java
source files still use HTML 4 features, and so the generated
documentation would not be fully HTML 5 compliant.
The new output still has the basic frame layout, but it now uses
<iframe> tags, instead of the HTML4-era tags. It was an explicit
non-goal of the HTML 5 to change the general visual appearance of the
generated docs. But, we are still discussing what it means to
eliminate the frame layout, with "search" being an important component
of any such design.
It will be a separate engineering effort to update the doc comments in
the platform source files to change HTML4-only features into equivalent
HTML 5 features. Once that has been done, I expect that we will throw
the switch and generate HTML 5 platform documentation.
Of course, anyone is free to use the -html5 option on their own
documentation, or to take an OpenJDK forest and to tweak the options in
make/Javadoc.gmk to generate "mostly compliant" HTML 5 docs. The Doctype
and the HTML generated by javadoc itself will all be valid HTML 5, but
the doc comments still get passed through, and so may lead to validation
errors if you were to check the generated files for compliance.
-- Jon
On 08/19/2015 12:47 AM, Sven Reimers wrote:
> 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
> <mailto: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 <tel:%2B61%202%209550%205001> fax +61 2
> 9550 4001 <tel:%2B61%202%209550%204001>
> 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
More information about the javadoc-next-dev
mailing list