search

asciidoctor / asciidoclet

:clipboard: A Javadoc Doclet based on Asciidoctor that lets you write Javadoc in the AsciiDoc syntax.
https://github.com/asciidoctor/asciidoclet
Apache License 2.0
132 stars 40 forks source link

Add clear documentation to configure opens for the different java versions #127

Closed abelsromero closed 2 months ago

abelsromero commented 3 months ago

We should make it clear why it's needed, what warnings are expected and the differences between Java versions.

EDIT: ℹ️ For reference: the final configuration is available in the docs https://docs.asciidoctor.org/asciidoclet/latest/usage/

abelsromero commented 3 months ago

From some personal testing (take as non definitive)

For java 11

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

For ava 17 & 21 also add

    <additionalJOption>--add-opens=jdk.compiler/com.sun.tools.javac.api=asciidoclet</additionalJOption>
    <additionalJOption>-J--add-opens=jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED</additionalJOption>
    <additionalJOption>--add-opens=jdk.compiler/com.sun.tools.javac.parser=asciidoclet</additionalJOption>
    <additionalJOption>-J--add-opens=jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED</additionalJOption>
amusarra commented 2 months ago

Hi @abelsromero I try with this

          <additionalJOptions>
            <additionalJOption>--add-opens=jdk.compiler/com.sun.tools.javac.api=asciidoclet</additionalJOption>
            <additionalJOption>-J--add-opens=jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED</additionalJOption>
            <additionalJOption>--add-opens=jdk.compiler/com.sun.tools.javac.parser=asciidoclet</additionalJOption>
            <additionalJOption>-J--add-opens=jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED</additionalJOption>
            <additionalJOption>-Xdoclint:all,-html,-accessibility</additionalJOption>
          </additionalJOptions>

but I'm getting errors

 occurred in Javadoc report generation:
[ERROR] Exit code: 4
[ERROR] warning: BASEDIR must be present for includes or file reference features to work properly
[ERROR] error: fatal error encountered: java.lang.IllegalAccessError: superclass access check failed: class org.asciidoctor.asciidoclet.AsciidoctorFilteredEnvironment (in unnamed module @0xeb6449b) cannot access class jdk.javadoc.internal.tool.DocEnvImpl (in module jdk.javadoc) because module jdk.javadoc does not export jdk.javadoc.internal.tool to unnamed module @0xeb6449b
[ERROR] error: Please file a bug against the javadoc tool via the Java bug reporting page
[ERROR]   (https://bugreport.java.com) after checking the Bug Database (https://bugs.java.com)
[ERROR]   for duplicates. Include error messages and the following diagnostic in your report. Thank you.
[ERROR] java.lang.IllegalAccessError: superclass access check failed: class org.asciidoctor.asciidoclet.AsciidoctorFilteredEnvironment (in unnamed module @0xeb6449b) cannot access class jdk.javadoc.internal.tool.DocEnvImpl (in module jdk.javadoc) because module jdk.javadoc does not export jdk.javadoc.internal.tool to unnamed module @0xeb6449b
[ERROR]     at java.base/java.lang.ClassLoader.defineClass1(Native Method)
[ERROR]     at java.base/java.lang.ClassLoader.defineClass(ClassLoader.java:1027)
[ERROR]     at java.base/java.security.SecureClassLoader.defineClass(SecureClassLoader.java:150)
[ERROR]     at java.base/java.net.URLClassLoader.defineClass(URLClassLoader.java:524)
[ERROR]     at java.base/java.net.URLClassLoader$1.run(URLClassLoader.java:427)
[ERROR]     at java.base/java.net.URLClassLoader$1.run(URLClassLoader.java:421)
[ERROR]     at java.base/java.security.AccessController.doPrivileged(AccessController.java:714)
[ERROR]     at java.base/java.net.URLClassLoader.findClass(URLClassLoader.java:420)
[ERROR]     at java.base/java.lang.ClassLoader.loadClass(ClassLoader.java:593)
[ERROR]     at java.base/java.lang.ClassLoader.loadClass(ClassLoader.java:526)
[ERROR]     at org.asciidoctor.asciidoclet.Asciidoclet.run(Asciidoclet.java:217)
[ERROR]     at jdk.javadoc/jdk.javadoc.internal.tool.Start.parseAndExecute(Start.java:575)
[ERROR]     at jdk.javadoc/jdk.javadoc.internal.tool.Start.begin(Start.java:398)
[ERROR]     at jdk.javadoc/jdk.javadoc.internal.tool.Start.begin(Start.java:347)
[ERROR]     at jdk.javadoc/jdk.javadoc.internal.tool.Main.execute(Main.java:57)
[ERROR]     at jdk.javadoc/jdk.javadoc.internal.tool.Main.main(Main.java:46)
[ERROR] 2 errors
[ERROR] 1 warning
[ERROR] Command line was: /Library/Java/JavaVirtualMachines/amazon-corretto-21.jdk/Contents/Home/bin/javadoc --add-opens=jdk.compiler/com.sun.tools.javac.api=asciidoclet -J--add-opens=jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED --add-opens=jdk.compiler/com.sun.tools.javac.parser=asciidoclet -J--add-opens=jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED -Xdoclint:all,-html,-accessibility @options @packages
[ERROR]
amusarra commented 2 months ago

@abelsromero resolved with this configuration.

          <additionalJOptions>
            <additionalJOption>-J--add-opens=jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED</additionalJOption>
            <additionalJOption>-J--add-opens=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.parser=ALL-UNNAMED</additionalJOption>
            <additionalJOption>-J--add-exports=jdk.javadoc/jdk.javadoc.internal.tool=ALL-UNNAMED</additionalJOption>
            <additionalJOption>-Xdoclint:all,-html,-accessibility</additionalJOption>
          </additionalJOptions>

Thanks.
Antonio.
abelsromero commented 2 months ago

I updated the initial post linking to the docs, I see how the incorrect block above can be confusing.