Thank you Chris for bringing up this topic and your suggestions. I prefer option 3. Given we are not usually paying attention to the javadoc configs, I would like to minimize the maintenance cost and I don't want to block the upcoming release schedule.
Thanks, Akira On Sat, Jan 24, 2026 at 3:30 AM Chris Nauroth <[email protected]> wrote: > > 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 --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
