JAVA-2560 : Use jdk.javadoc.doclet package #470

fhassak · 2018-04-27T21:59:16Z

Migration guide :

https://docs.oracle.com/javase/9/docs/api/jdk/javadoc/doclet/package-summary.html#migration

Generated API documention on my machine :

URLs are correctly generated.

Javadoc Search

JEP 225 added a search box :

Javadoc and HTML

Javadoc tools currently generates pages in HTML 4.01 :

JEP 224 added an option to generate HTML5.
I have tried this option and it's not working. I need to convert documentation comments written using HTML 4 to HTML5. And there are others rendering issue (with frame).
There is a lot of issue about javadoc tools : JIRA

Build with :

------------------------------------------------------------
Gradle 4.5.1
------------------------------------------------------------

Build time:   2018-02-05 13:22:49 UTC
Revision:     37007e1c012001ff09973e0bd095139239ecd3b3

Groovy:       2.4.12
Ant:          Apache Ant(TM) version 1.9.9 compiled on February 2 2017
JVM:          9.0.4 (Oracle Corporation 9.0.4+11)
OS:           Linux 3.13.0-137-generic amd64

Gradle docs task is not working on Windows : GRADLE-3099

Farès

fhassak · 2018-04-27T22:02:08Z

driver-core/src/main/com/mongodb/client/model/Projections.java

@@ -185,7 +185,6 @@ public static Bson fields(final Bson... projections) {
     *
     * @param projections the list of projections to combine
     * @return the combined projection
-     * @mongodb.driver.manual


Text (url path) is mandatory when generating javadoc. see DocTaglet.java

fhassak · 2018-04-27T22:05:38Z

util/src/main/DocTaglet.java

+        Set<Location> allowedLocations = new HashSet<Location>();
+        allowedLocations.addAll(Arrays.asList(Location.CONSTRUCTOR, Location.METHOD, Location.FIELD, Location.OVERVIEW, Location.PACKAGE,
+                Location.TYPE));
+        return allowedLocations;


We can't use Java 9 style :

return Set.of(Location.CONSTRUCTOR, Location.METHOD, Location.FIELD, Location.OVERVIEW, Location.PACKAGE, Location.TYPE);

because of source compatibility to java 6.

/mongo-java-driver/util/src/main/DocTaglet.java:30: error: static interface method invocations are not supported in -source 1.6 (use -source 8 or higher to enable static interface method invocations)

At compile time :

warning: [options] source value 1.6 is obsolete and will be removed in a future release warning: [options] target value 1.6 is obsolete and will be removed in a future release warning: [options] To suppress warnings about obsolete options, use -Xlint:-options.

Understood.

IntelliJ does however suggest this small change:

return new HashSet<Location>( asList(Location.CONSTRUCTOR, Location.METHOD, Location.FIELD, Location.OVERVIEW, Location.PACKAGE, Location.TYPE));

Yes, i made this change but not yet committed. We can also import statically Location.* :

return new HashSet<Location>(asList(CONSTRUCTOR, METHOD, FIELD, OVERVIEW, PACKAGE, TYPE));

Or maybe:

return new HashSet(asList(Location.values()));

fhassak · 2018-04-27T22:18:10Z

util/src/main/DocTaglet.java

-        for (Tag t : tags) {
-            buf.append("   <dd>").append(genLink(t.text())).append("</dd>%n");
+        for (DocTree t : tags) {
+            String text = ((UnknownBlockTagTree) t).getContent().get(0).toString();


if there is an empty tag @mongodb.driver.manual without text (like in Projections.fields), getContent().get(0) throw an exception.
I think text is mandatory in tag. So it's good to failed and not necessarry to add control ?

if (getContent().size() > 0 ) { text = getContent().get(0).toString(); }

Or, we can add default value (default path + default display (see genLink method) ?

javadoc: error - An internal exception has occurred. (java.lang.IndexOutOfBoundsException: Index: 0, Size: 0) Please file a bug against the javadoc tool via the Java bug reporting page (http://bugreport.java.com) after checking the Bug Database (http://bugs.java.com) for duplicates. Include error messages and the following diagnostic in your report. Thank you. java.lang.IndexOutOfBoundsException: Index: 0, Size: 0 at jdk.compiler/com.sun.tools.javac.util.List.get(List.java:490) at DocTaglet.toString(DocTaglet.java:48) at jdk.javadoc/jdk.javadoc.internal.doclets.toolkit.taglets.UserTaglet.getTagletOutput(UserTaglet.java:147) at jdk.javadoc/jdk.javadoc.internal.doclets.toolkit.taglets.TagletWriter.genTagOutput(TagletWriter.java:238) at jdk.javadoc/jdk.javadoc.internal.doclets.formats.html.HtmlDocletWriter.addTagsInfo(HtmlDocletWriter.java:333) at jdk.javadoc/jdk.javadoc.internal.doclets.formats.html.MethodWriterImpl.addTags(MethodWriterImpl.java:207) at jdk.javadoc/jdk.javadoc.internal.doclets.toolkit.builders.MethodBuilder.buildTagInfo(MethodBuilder.java:206) at jdk.javadoc/jdk.javadoc.internal.doclets.toolkit.builders.MethodBuilder.buildMethodDoc(MethodBuilder.java:153) at jdk.javadoc/jdk.javadoc.internal.doclets.toolkit.builders.MethodBuilder.build(MethodBuilder.java:128) at jdk.javadoc/jdk.javadoc.internal.doclets.toolkit.builders.ClassBuilder.buildMethodDetails(ClassBuilder.java:393) at jdk.javadoc/jdk.javadoc.internal.doclets.toolkit.builders.ClassBuilder.buildMemberDetails(ClassBuilder.java:341) at jdk.javadoc/jdk.javadoc.internal.doclets.toolkit.builders.ClassBuilder.buildClassDoc(ClassBuilder.java:145) at jdk.javadoc/jdk.javadoc.internal.doclets.toolkit.builders.ClassBuilder.build(ClassBuilder.java:120) at jdk.javadoc/jdk.javadoc.internal.doclets.formats.html.HtmlDoclet.generateClassFiles(HtmlDoclet.java:267) at jdk.javadoc/jdk.javadoc.internal.doclets.toolkit.AbstractDoclet.generateClassFiles(AbstractDoclet.java:290) at jdk.javadoc/jdk.javadoc.internal.doclets.toolkit.AbstractDoclet.generateClassFiles(AbstractDoclet.java:272) at jdk.javadoc/jdk.javadoc.internal.doclets.toolkit.AbstractDoclet.startGeneration(AbstractDoclet.java:211) at jdk.javadoc/jdk.javadoc.internal.doclets.toolkit.AbstractDoclet.run(AbstractDoclet.java:117) at jdk.javadoc/jdk.javadoc.doclet.StandardDoclet.run(StandardDoclet.java:72) at jdk.javadoc/jdk.javadoc.internal.tool.Start.parseAndExecute(Start.java:581) at jdk.javadoc/jdk.javadoc.internal.tool.Start.begin(Start.java:430) at jdk.javadoc/jdk.javadoc.internal.tool.Start.begin(Start.java:343) at jdk.javadoc/jdk.javadoc.internal.tool.Main.execute(Main.java:63) at jdk.javadoc/jdk.javadoc.internal.tool.Main.main(Main.java:52)

It's fine to fail fast here.

fhassak · 2018-04-27T22:19:37Z

util/src/main/DocTaglet.java

-            buf.append("   <dd>").append(genLink(t.text())).append("</dd>%n");
+        for (DocTree t : tags) {
+            String text = ((UnknownBlockTagTree) t).getContent().get(0).toString();
+            buf.append("   <dd>").append(genLink(text)).append("</dd><br/>");


<br/> must be removed by #468

Is this what's creating the extra white below the MongoDB Documentation and Since Server Release paragraphs, as seen in the first screen shot? And #468 will fix it?

Yes ! I suggest to merge #468 on master. I will rebase and fix conflict on this line

fhassak · 2018-04-28T10:26:12Z

.travis.yml

@@ -2,7 +2,7 @@ dist: trusty
 sudo: true
 language: java
 jdk:
- oraclejdk8
+- oraclejdk9


Now, we need JDK 9 to build project. If you merge on master, all next commits must be compiled with jdk 9.

fhassak · 2018-04-28T11:09:23Z

build.gradle

@@ -285,6 +285,7 @@ def setJavaDocOptions(MinimalJavadocOptions options) {
    options.encoding = 'UTF-8'
    options.charSet 'UTF-8'
    options.docEncoding 'UTF-8'
+    options.addBooleanOption("html4", true)


Building with JDK 10, show me this warning :

javadoc: warning - You have not specified the version of HTML to use. The default is currently HTML 4.01, but this will change to HTML5 in a future release. To suppress this warning, please specify the version of HTML used in your documentation comments and to be generated by this doclet, using the -html4 or -html5 options.

HTML 5 is not working...

fhassak · 2018-04-29T18:49:03Z

build.gradle

@@ -277,14 +277,16 @@ task docs(type: Javadoc) {
 def setJavaDocOptions(MinimalJavadocOptions options) {
    options.author = true
    options.version = true
-    options.links 'http://docs.oracle.com/javase/7/docs/api/'
+    options.links 'https://docs.oracle.com/javase/9/docs/api/'


Now, we have link to java package :

Not working without https :

jyemin · 2018-04-30T15:34:35Z

Thanks for the contribution @fhassak.

Have you had any luck getting IntelliJ to compile this? When I Rebuild Project I get:

Information:java: Errors occurred while compiling module 'util_main'
Information:javac 9 was used to compile java sources
Information:4/30/18, 12:16 PM - Compilation completed with 21 errors and 3 warnings in 3s 514ms
Warning:java: source value 1.6 is obsolete and will be removed in a future release
Warning:java: target value 1.6 is obsolete and will be removed in a future release
Warning:java: To suppress warnings about obsolete options, use -Xlint:-options.
    /Users/jeff/mongo-java-driver/util/src/main/DocTaglet.java
        Error:(17, 30) java: package com.sun.source.doctree does not exist
        Error:(19, 26) java: package jdk.javadoc.doclet does not exist

even though they clearly do exist.

jyemin · 2018-04-30T17:18:53Z

I figured out the IntelliJ issue. You have to uncheck the "Use '--release' option for cross-compilation (Java 9 and later)" on the "Build, Execution, Deployment > Compiler > Java Compiler" preference page. Otherwise when it builds it sets the "--release" command line argument for javac to "--release 6" based on the "targetCompatibility = JavaVersion.VERSION_1_6" in build.gradle.

jyemin · 2018-04-30T17:54:23Z

Squashed, rebased, and merged to master at 74b9ff6.

Thanks so much for this contribution. The javadoc looks so much better now.

fhassak commented Apr 28, 2018

View reviewed changes

fhassak commented Apr 29, 2018

View reviewed changes

fhassak added 6 commits April 30, 2018 19:00

JAVA-2560 : Use jdk.javadoc.doclet package

cbd4607

Generate javadoc

f08f9bf

Specify the version of HTML used in javadoc

f6f38b2

Java 9 is required

ebc75b4

Update link to the Java platform packages

7ccec93

code review

fe879fe

fhassak force-pushed the JAVA-2560 branch from 0f6ccca to fe879fe Compare April 30, 2018 17:27

jyemin self-assigned this Apr 30, 2018

jyemin closed this Apr 30, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

JAVA-2560 : Use jdk.javadoc.doclet package #470

JAVA-2560 : Use jdk.javadoc.doclet package #470

fhassak commented Apr 27, 2018 •

edited

fhassak Apr 27, 2018

fhassak Apr 27, 2018

jyemin Apr 30, 2018

fhassak Apr 30, 2018

fhassak Apr 30, 2018

fhassak Apr 27, 2018 •

edited

jyemin Apr 30, 2018

fhassak Apr 27, 2018

jyemin Apr 30, 2018

fhassak Apr 30, 2018

jyemin Apr 30, 2018

fhassak Apr 28, 2018

fhassak Apr 28, 2018

fhassak Apr 29, 2018

jyemin commented Apr 30, 2018 •

edited

jyemin commented Apr 30, 2018

jyemin commented Apr 30, 2018

JAVA-2560 : Use jdk.javadoc.doclet package #470

JAVA-2560 : Use jdk.javadoc.doclet package #470

Conversation

fhassak commented Apr 27, 2018 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

fhassak Apr 27, 2018 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jyemin commented Apr 30, 2018 • edited

jyemin commented Apr 30, 2018

jyemin commented Apr 30, 2018

fhassak commented Apr 27, 2018 •

edited

fhassak Apr 27, 2018 •

edited

jyemin commented Apr 30, 2018 •

edited