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
134 stars 39 forks source link

Support Java 9, 10, and beyond (parent issue) #76

Open msgilligan opened 6 years ago

msgilligan commented 6 years ago

There are 2 phases of implementation for supporting Java 9 and later.

  1. Run under Java 9 and later (but build using Java 7/8) -- this was completed and released as AsciiDoclet 1.5.6.
  1. Build under Java 9/10/11 (presumably using the new Doclet API)

Note: We had previously considered an implementation phase of "Run under Java 10 and later (but build using Java 7/8)", but we have decided to directly move to the new Doclet API instead.

johncarl81 commented 6 years ago

Yes!

LightGuard commented 5 years ago

At this point, I think it would be good to make a cut. Version 1.5.x should be runnable under JDK 8 and lower. Anything new at this point should be using the new Docklet API and require at least JDK 9.

msgilligan commented 4 years ago

At this point, I think it would be good to make a cut. Version 1.5.x should be runnable under JDK 8 and lower. Anything new at this point should be using the new Docklet API and require at least JDK 9.

A year later this is more obviously true. JDK 11 is out with growing adoptions and compiles back to JDK 7 (back to JDK 6 with a deprecation warning.)

I think the first step is to create a new branch, rebase PR #96 to that branch, and merge it.

We can also either rename this issue to "Create a 2.0 release" or create a new issue and link it to this one.

I have a certain amount of time available, but I'm not sure it's enough to finish this by myself. I'm hoping others will help and I also don't have the ability to make a new release.

It looks like @chrisvest is still willing to help with his PR.

@johncarl81 @mojavelinux @LightGuard Do any of you have time to help with this?

johncarl81 commented 4 years ago

I have a little time and would like to be part of the process for sure. I like that the fork has been used for some time.

I know that Java 11 compiles back to 7, bit isn't the real issue is the different javadoclet API?

On Fri, Jul 10, 2020, 7:08 PM Sean Gilligan notifications@github.com wrote:

At this point, I think it would be good to make a cut. Version 1.5.x should be runnable under JDK 8 and lower. Anything new at this point should be using the new Docklet API and require at least JDK 9.

A year later this is more obviously true. JDK 11 is out with growing adoptions and compiles back to JDK 7 (back to JDK 6 with a deprecation warning.)

I think the first step is to create a new branch, rebase PR #96 https://github.com/asciidoctor/asciidoclet/pull/96 to that branch, and merge it.

We can also either rename this issue to "Create a 2.0 release" or create a new issue and link it to this one.

I have a certain amount of time available, but I'm not sure it's enough to finish this by myself. I'm hoping others will help and I also don't have the ability to make a new release.

It looks like @chrisvest https://github.com/chrisvest is still willing to help with his PR.

@johncarl81 https://github.com/johncarl81 @mojavelinux https://github.com/mojavelinux @LightGuard https://github.com/LightGuard Do any of you have time to help with this?

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/asciidoctor/asciidoclet/issues/76#issuecomment-656956167, or unsubscribe https://github.com/notifications/unsubscribe-auth/AABIZKLGQH5U5HU7DRPI7DDR263SBANCNFSM4FCDR2RA .

msgilligan commented 4 years ago

I know that Java 11 compiles back to 7, bit isn't the real issue is the different javadoclet API?

Right, so, so I'm saying we create AsciiDoclet 2.0 and have it use only the new API and require Java 9, 10, or 11 as a minimum and focus all new development on that version. It will allow people to compile code targeting all thew way back to Java 7 (or 6 with warnings) and with 11 having LTS and decent adoption, I don' think it's entirely unreasonable to require Java 11 as a minimum. Java 9 as a minimum would be ideal, but that might be harder to develop/maintain. I'm not sure if PR #96 will run under JDK 9 or 10. (I'm not going to have the bandwidth to back port PR #96 to earlier JDKs if it doesn't work there already, but I'd prefer a release that works with JDK 9 if someone steps forward that is willing to do whatever work is needed.)

@chrisvest Do you know what is required to make PR #96 run on JDK 9?

chrisvest commented 4 years ago

The PR relies on some utility methods that are not available in Java 9 or 10.

More importantly, #96 is not really a clean port to the new javadoc APIs. It is still relying on extending the standard doclet, which is not supported because it’s hidden by JPMS, and it’s still relying on APIs that are deprecated for removal.

msgilligan commented 4 years ago

The PR relies on some utility methods that are not available in Java 9 or 10.

That sounds relatively easy to fix. Would you agree?

More importantly, #96 is not really a clean port to the new javadoc APIs. It is still relying on extending the standard doclet, which is not supported because it’s hidden by JPMS, and it’s still relying on APIs that are deprecated for removal.

Do you (or anyone else) have any ideas for a longer-term approach that might be a cleaner port to the new API?

chrisvest commented 4 years ago

Do you (or anyone else) have any ideas for a longer-term approach that might be a cleaner port to the new API?

The new API is kind of limited. And there are only bad ways to modify the behaviour of the official standard doclet, which means the "proper" way involves rebuilding all the functionality provided by the standard doclet.

One approach around this, could be to copy or shade the standard doclet from OpenJDK. It's GPL-2.0, so this may require asciidoclet to be relicensed.

xenoterracide commented 8 months ago

well... I was going to raise an issue, this is unfortunate. I guess this is a dead project.

> Task :test-app:javadoc FAILED
Exception in thread "main" java.lang.NoClassDefFoundError: com/sun/javadoc/Doclet
        at java.base/java.lang.ClassLoader.defineClass1(Native Method)
        at java.base/java.lang.ClassLoader.defineClass(ClassLoader.java:1027)
        at java.base/java.security.SecureClassLoader.defineClass(SecureClassLoader.java:150)
        at java.base/java.net.URLClassLoader.defineClass(URLClassLoader.java:524)
        at java.base/java.net.URLClassLoader$1.run(URLClassLoader.java:427)
        at java.base/java.net.URLClassLoader$1.run(URLClassLoader.java:421)
        at java.base/java.security.AccessController.doPrivileged(AccessController.java:714)
        at java.base/java.net.URLClassLoader.findClass(URLClassLoader.java:420)
        at java.base/java.lang.ClassLoader.loadClass(ClassLoader.java:593)
        at java.base/java.lang.ClassLoader.loadClass(ClassLoader.java:526)
        at jdk.javadoc/jdk.javadoc.internal.tool.Start.loadDocletClass(Start.java:800)
        at jdk.javadoc/jdk.javadoc.internal.tool.Start.preprocess(Start.java:771)
        at jdk.javadoc/jdk.javadoc.internal.tool.Start.begin(Start.java:376)
        at jdk.javadoc/jdk.javadoc.internal.tool.Start.begin(Start.java:347)
        at jdk.javadoc/jdk.javadoc.internal.tool.Main.execute(Main.java:57)
        at jdk.javadoc/jdk.javadoc.internal.tool.Main.main(Main.java:46)
xenoterracide commented 8 months ago

Oh, and openjdk isn't really GPL 2, that's kind of a lie due to the classpath exception. Although if you shade it, I'm not entirely certain. I would speculate (I am not a copyright specialist lawyer) that if you aren't modifying those classes outside of the packagename transformation, then it really shouldn't matter. At worst that would constitute fair use (see google v oracle).

On another hand, you should probably make like the unsafe people and tell them what you need, maybe a new public api could be made available.

abelsromero commented 8 months ago

I guess this is a dead project.

It's true there's not an active maintainer, but it can be brought back if someone puts some time :eyes: