Going to jdk 17 and 21 (#124)

* Ignore non-`LazyDocCommentTable` instances as they make the JavaDoc generation due to type mismatch.
* Remove unnecessary options given to JavaDoc.
* Add stylesheet for Java17 and Jva21.
* Remove several pieces of unnecessary code.
* Provide an implementation note for AsciiDocTrees#getType(DocTreePath) method.
Also, make pom.xml use JDK 11 for compilation and testing since it seems working with JDK21 project.
* Improve an implementation note for AsciiDocTrees#getType(DocTreePath) method.
* Improve several JavaDocs.
* Update unit tests.
* Enable AsciidocletIntegrationTest.

Closes #122 
---------

Co-authored-by: Hiroshi Ukai <dakusui@gamil.com>

pom.xml

@@ -69,6 +69,8 @@
                     <source>11</source>
                     <target>11</target>
                     <compilerArgs>
+                        <arg>--add-exports</arg>
+                        <arg>jdk.javadoc/jdk.javadoc.internal.api=asciidoclet</arg>
                         <arg>--add-exports</arg>
                         <arg>jdk.javadoc/jdk.javadoc.internal.tool=asciidoclet</arg>
                         <arg>--add-exports</arg>
@@ -77,6 +79,14 @@
                         <arg>jdk.compiler/com.sun.tools.javac.tree=asciidoclet</arg>
                         <arg>--add-exports</arg>
                         <arg>jdk.compiler/com.sun.tools.javac.model=asciidoclet</arg>
+                        <arg>--add-exports</arg>
+                        <arg>jdk.compiler/com.sun.tools.javac.util=asciidoclet</arg>
+                        <arg>--add-exports</arg>
+                        <arg>jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED</arg>
+                        <arg>--add-exports</arg>
+                        <arg>jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED</arg>
+                        <arg>--add-exports</arg>
+                        <arg>jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED</arg>
                     </compilerArgs>
                 </configuration>
             </plugin>
@@ -86,6 +96,9 @@
                 <version>3.2.5</version>
                 <configuration>
                     <argLine>
+                        --add-exports jdk.compiler/com.sun.tools.javac.parser=asciidoclet
+                        --add-exports jdk.compiler/com.sun.tools.javac.util=asciidoclet
+                        --add-opens jdk.compiler/com.sun.tools.javac.parser=asciidoclet
                         --add-exports jdk.javadoc/jdk.javadoc.internal.tool=asciidoclet
                     </argLine>
                 </configuration>
@@ -119,14 +132,19 @@
                 <configuration>
                     <source>11</source>
                     <additionalJOptions>
+                        <additionalJOption>--add-exports=jdk.javadoc/jdk.javadoc.internal.api=asciidoclet</additionalJOption>
                         <additionalJOption>--add-exports=jdk.javadoc/jdk.javadoc.internal.tool=asciidoclet</additionalJOption>
+                        <additionalJOption>--add-exports=jdk.compiler/com.sun.tools.javac.api=asciidoclet</additionalJOption>
                         <additionalJOption>--add-exports=jdk.compiler/com.sun.tools.javac.parser=asciidoclet</additionalJOption>
                         <additionalJOption>--add-exports=jdk.compiler/com.sun.tools.javac.tree=asciidoclet</additionalJOption>
                         <additionalJOption>--add-exports=jdk.compiler/com.sun.tools.javac.model=asciidoclet</additionalJOption>
-                        <additionalJOption>-J--add-exports=jdk.javadoc/jdk.javadoc.internal.tool=ALL-UNNAMED</additionalJOption>
-                        <additionalJOption>-J--add-exports=jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED</additionalJOption>
-                        <additionalJOption>-J--add-exports=jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED</additionalJOption>
-                        <additionalJOption>-J--add-exports=jdk.compiler/com.sun.tools.javac.model=ALL-UNNAMED</additionalJOption>
+                        <additionalJOption>--add-opens=jdk.compiler/com.sun.tools.javac.api=asciidoclet</additionalJOption>
+                        <additionalJOption>--add-opens=jdk.compiler/com.sun.tools.javac.parser=asciidoclet</additionalJOption>
+                        <additionalJOption>-J--add-opens=jdk.javadoc/jdk.javadoc.internal.api=ALL-UNNAMED</additionalJOption>
+                        <additionalJOption>-J--add-opens=jdk.javadoc/jdk.javadoc.internal.tool=ALL-UNNAMED</additionalJOption>
+                        <additionalJOption>-J--add-opens=jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED</additionalJOption>
+                        <additionalJOption>-J--add-opens=jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED</additionalJOption>
+                        <additionalJOption>-J--add-opens=jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED</additionalJOption>
                         <additionalJOption>-Xdoclint:all,-html,-accessibility</additionalJOption>
                     </additionalJOptions>
                     <doclet>org.asciidoctor.asciidoclet.Asciidoclet</doclet>

src/main/java/module-info.java

@@ -13,10 +13,14 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+/**
+ * A module-info for `asciidoclet`.
+ */
 module asciidoclet {
     requires java.base;
+    requires jdk.compiler;
     requires jdk.javadoc;
-    requires asciidoctorj.api;
     requires asciidoctorj;
+    requires asciidoctorj.api;
     exports org.asciidoctor.asciidoclet;
 }

src/main/java/org/asciidoctor/asciidoclet/AntPathMatcher.java

@@ -53,7 +53,16 @@ private AntPathMatcher(final char pathSeparator, boolean ignoreCase, boolean mat
         this.matchStart = matchStart;
         this.trimTokens = trimTokens;
     }
-
+
+    /**
+     * Checks if a `path` matches with a given `pattern`.
+     * Is this method really necessary?
+     *
+     * @param pattern A pattern to be checked with a `path`.
+     * @param path A path to be checked
+     * @return `true` if `path` matches `pattern`. `false`, otherwise.
+     */
+
     public boolean isMatch(final String pattern, final String path) {
         if (pattern.isEmpty()) {
             return path.isEmpty();
@@ -120,38 +129,68 @@ private boolean equal(final char pathChar, final char patternChar) {
         }
         return pathChar == patternChar;
     }
-
+
+    /**
+     * A builder class for `AndPathMatcher`.
+     * Is this class really necessary?
+     * // A comment to suppress warnings during JavaDoc generation by AsciiDoclet.
+     */
     public static final class Builder {
 
         private char pathSeparator = '/';
         private boolean ignoreCase = false;
         private boolean matchStart = false;
         private boolean trimTokens = false;
-
+
+        /**
+         * Creates {@link Builder} object.
+         */
         public Builder() {
 
         }
-
+
+        /**
+         * Sets `pathSeparator` to this object.
+         *
+         * @param pathSeparator `pathSeparator` to be set.
+         * @return returns this object.
+         */
         public Builder withPathSeparator(final char pathSeparator) {
             this.pathSeparator = pathSeparator;
             return this;
         }
-
+
+        /**
+         * Sets `ignoreCase` to this object to `true`.
+         * @return returns this object.
+         */
         public Builder withIgnoreCase() {
             this.ignoreCase = true;
             return this;
         }
-
+
+        /**
+         * Sets `matchStart` to this object to `true`.
+         * @return returns this object.
+         */
         public Builder withMatchStart() {
             this.matchStart = true;
             return this;
         }
-
+
+        /**
+         * Sets `trimTokens` to this object to `true`.
+         * @return returns this object.
+         */
         public Builder withTrimTokens() {
             this.trimTokens = true;
             return this;
         }
-
+
+        /**
+         * Creates and returns {@link AntPathMatcher} object.
+         * @return A built {@link AntPathMatcher} object.
+         */
         public AntPathMatcher build() {
             return new AntPathMatcher(pathSeparator, ignoreCase, matchStart, trimTokens);
         }

src/main/java/org/asciidoctor/asciidoclet/AsciiDocTrees.java

@@ -49,6 +49,7 @@
 import java.io.FileNotFoundException;
 import java.io.IOException;
 import java.lang.reflect.Field;
+import java.lang.reflect.InvocationTargetException;
 import java.text.BreakIterator;
 import java.util.List;
 
@@ -88,19 +89,21 @@ public DocCommentTree getDocCommentTree(TreePath path) {
         // First we convert the asciidoctor to HTML inside the AST.
         JCTree.JCCompilationUnit cu = (JCTree.JCCompilationUnit) path.getCompilationUnit();
         LazyDocCommentTableProcessor.processComments(cu.docComments, this::convertToAsciidoctor);
-
         // Then we allow the normal javadoc parsing to continue on the asciidoctor result.
         return docTrees.getDocCommentTree(path);
     }
 
     private Tokens.Comment convertToAsciidoctor(Tokens.Comment comment) {
-        String javadoc = comment.getText();
-        String asciidoc = converter.convert(javadoc);
+        String asciidoc = convertJavadocStringToAsciidoctorString(comment.getText());
         AsciidocComment result = new AsciidocComment(asciidoc, comment);
-        System.err.println("");
         return result;
     }
-
+
+    private String convertJavadocStringToAsciidoctorString(String javadocString) {
+      return converter.convert(javadocString);
+    }
+
+
     @Override
     public DocCommentTree getDocCommentTree(Element e) {
         TreePath path = getPath(e);
@@ -151,7 +154,19 @@ public DocTreePath getDocTreePath(FileObject fileObject, PackageElement packageE
     public Element getElement(DocTreePath path) {
         return docTrees.getElement(path);
     }
-
+
+    // Not giving @Override in order to make this class compilable under all of JDK 11, 17, 21.
+    public TypeMirror getType(DocTreePath path) {
+        // In order to make this method compilable with JDK11, which doesn't define DocTrees#getType method,
+        // and make this method work with JDK 17 and later, invoke the DocTrees#getType(DocTreePath) method reflectively.
+        // Once we decide to stop supporting JDK 11, just call getType directly.
+      try {
+        return (TypeMirror) DocTrees.class.getMethod("getType", DocTreePath.class).invoke(docTrees, path);
+      } catch (NoSuchMethodException | IllegalAccessException | InvocationTargetException e) {
+        throw new RuntimeException(e);
+      }
+    }
+
     @Override
     public List<DocTree> getFirstSentence(List<? extends DocTree> list) {
         return docTrees.getFirstSentence(list);

src/main/java/org/asciidoctor/asciidoclet/Asciidoclet.java

@@ -178,7 +178,10 @@ public class Asciidoclet implements Doclet {
     private DocletOptions docletOptions;
     private Stylesheets stylesheets;
     private Reporter reporter;
-
+
+    /**
+     * Creates a new {@link Asciidoclet} object.
+     */
     public Asciidoclet() {
         standardDoclet = new StandardDoclet();
     }

src/main/java/org/asciidoctor/asciidoclet/AsciidocletOptions.java

@@ -19,20 +19,62 @@
 
 import java.util.List;
 
+/**
+ * An `enum` to define options supported by AsciiDoclet.
+ */
+// TODO: ideally, the `options.adoc` should be generated from comments in this file.
 public enum AsciidocletOptions implements Doclet.Option {
+    /**
+     * Check Doclet Options documentation.
+     */
     ENCODING("encoding"),
+    /**
+     * Check Doclet Options documentation.
+     */
     OVERVIEW("overview"),
+    /**
+     * Check Doclet Options documentation.
+     */
     BASEDIR("base-dir"),
+    /**
+     * Check Doclet Options documentation.
+     */
     STYLESHEET("stylesheetfile"),
+    /**
+     * Check Doclet Options documentation.
+     */
     ATTRIBUTE("a"),
+    /**
+     * Check Doclet Options documentation.
+     */
     ATTRIBUTE_LONG("attribute"),
+    /**
+     * Check Doclet Options documentation.
+     */
     INCLUDE_FILTER("asciidoclet-include"),
+    /**
+     * Check Doclet Options documentation.
+     */
     EXCLUDE_FILTER("asciidoclet-exclude"),
+    /**
+     * Check Doclet Options documentation.
+     */
     ATTRIBUTES_FILE("attributes-file"),
+    /**
+     * Check Doclet Options documentation.
+     */
     GEM_PATH("gem-path"),
+    /**
+     * Check Doclet Options documentation.
+     */
     REQUIRE("r"),
+    /**
+     * Check Doclet Options documentation.
+     */
     REQUIRE_LONG("require");
-
+    /**
+     * Check Doclet Options documentation.
+     */
     private final String name;
 
     AsciidocletOptions(String name) {

src/main/java/org/asciidoctor/asciidoclet/AsciidoctorConverter.java

@@ -181,7 +181,21 @@ private String convert(String input, boolean inline) {
         if (input.trim().isEmpty()) {
             return "";
         }
-        options.setDocType(inline ? INLINE_DOCTYPE : "");
+        // Setting doctype to null results in an NPE from asciidoctor.
+        // the default value from the command line is "article".
+        // https://docs.asciidoctor.org/asciidoctor/latest/cli/man1/asciidoctor/#options
+        // In general, in order to respect original doctype, we should do the following.
+        // options.setDocType(inline ?
+        //    INLINE_DOCTYPE :
+        //    options.map().containsKey(Options.DOCTYPE) ?
+        //        (String)options.map().get(Options.DOCTYPE) :
+        //        "article");
+        // However, this fix breaks AsciidoctorConverterTest#testParameterWithoutTypeTag.
+        // For now, I simply set it to "article", always.
+        options.setDocType(inline ?
+            INLINE_DOCTYPE :
+            "article"); // upstream sets this to "".
+
         return asciidoctor.convert(cleanJavadocInput(input), options);
     }
 

src/main/java/org/asciidoctor/asciidoclet/AsciidoctorFilteredEnvironment.java

@@ -23,6 +23,9 @@
 import javax.tools.StandardJavaFileManager;
 import java.io.IOException;
 
+/**
+ * An operating environment defined for AsciiDoclet.
+ */
 public class AsciidoctorFilteredEnvironment
         extends DocEnvImpl
         implements DocletEnvironment, AutoCloseable {

src/main/java/org/asciidoctor/asciidoclet/DocletOptions.java

@@ -41,7 +41,12 @@ public class DocletOptions {
     private List<String> attributes;
     private String gemPath;
     private List<String> requires;
-
+
+    /**
+     * Creates an {@link DocletOptions} object with a given {@link Reporter} object.
+     *
+     * @param reporter A {@link Reporter} object with which a new object is created.
+     */
     public DocletOptions(Reporter reporter) {
         this.reporter = reporter;
         encoding = Charset.defaultCharset();