Hello everyone, For those who aren't following it yet, I'd like to highlight HADOOP-19785, with an attached patch to switch JavaDoc generation to the standard doclet. This might be the last blocker before attempting some release candidates for 3.5.0.
https://github.com/apache/hadoop/pull/8182 To summarize, internal JDK 17 changes have broken our custom doclet that filters classes out of the docs based on our visibility annotations. For those of us who have looked already, it seems like the JDK has actively closed the door on the way we implemented the custom doclet and there is no alternative available. The PR proposes abandoning the custom doclet and switching to the standard. The impact of this change is that the number of documented classes increases from ~13,000 to ~126,000. Perhaps there could be some usefulness for contributors viewing internal docs, but a lot of it is boilerplate like auto-generated Protobuf classes that wouldn't be very useful. I'm concerned about the impact of this change on end users navigating the site. The only other options I can think of are: 1. Manually manage include/exclude rules in the maven-javadoc-plugin configuration. This sure sounds like a high maintenance burden and something easy to get wrong. 2. Maybe a mass refactoring such that @Public and @Private classes are always isolated in different Maven sub-modules would make the include/exclude configuration more manageable? I'm not really sure it would solve it, and it would be a huge change that massively delays 3.5.0. 3. Compromise by doing some targeted, easy-to-maintain exclusion rules (e.g. skip all that Protobuf stuff) to try to reduce the footprint. This option would still result in a lot more classes than we have in the docs today. I decided to start this thread to get more community impact. Is anyone else concerned about the increased footprint of the API docs, or am I overreacting? Can anyone think of other solutions? Chris Nauroth
