slfan1989 commented on PR #8182: URL: https://github.com/apache/hadoop/pull/8182#issuecomment-3766811692
> Hi @zhtttylz, you've implemented new custom Doclet to support JDK17 in #8038, however, unfortunately `mvn site` fails in Doclet part. The detail is below: > > 1. RootDocProcessor.process(env) creates a Proxy object that implements DocletEnvironment interface > 2. This proxy is passed to StandardDoclet.run(filtered) > 3. Inside the StandardDoclet, the javadoc internals (specifically WorkArounds.()) try to cast this proxy to the concrete implementation class jdk.javadoc.internal.tool.DocEnvImpl: https://github.com/jonathan-gibbons/jdk/blob/bc1e60c1bf91678ef18652a00aa2ce55b0446caa/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/WorkArounds.java#L112 > 4. The cast fails because a proxy object cannot be cast to a concrete implementation class > > It seems our custom doclet implementation is prohibited after https://bugs.openjdk.org/browse/JDK-8253736: > > > One particularly annoying wart is the cast on DocletEnvironment to DocEnvImpl, which effectively prevents using subtypes to carry additional info. It is not clear (even now) what the best way is to replace that logic. > > Now I feel it's becoming really hard to maintain Hadoop's custom Doclets, and therefore I would like to drop the custom implementation. The primary change is we are going to build Hadoop JavaDoc with `@LimitedPrivate`, `@Private` or `@Unstable` classes, which are now excluded by our custom Doclets. > > @slfan1989 @cnauroth @zhtttylz What do you think? @aajisaka Thanks for the detailed analysis — after reading through it, I fully agree that the cost of maintaining this custom Doclet has become unreasonably high. With OpenJDK continuing to clean up internal APIs (the trend starting from JDK-8253736 is only getting stronger), future compatibility will only get worse, and the next LTS might break it completely. I'm in favor of dropping the custom Doclet and switching to the standard doclet to generate complete JavaDocs (including all classes annotated with @Private / @Unstable / @LimitedPrivate). The main reasons are: - The maintenance burden is too heavy and takes away energy from more valuable work; - The visibility of these annotated classes has very limited impact on most downstream users — they shouldn't be depending on @Private APIs anyway; - On the positive side, having the full picture can actually help developers/contributors who want to dig into the implementation details. cc: @zhtttylz @cnauroth -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
