+1 for dropping Thanks for looking into this!
On Mon, 1 Sept 2025, 12:59 Elliotte Rusty Harold, <elh...@ibiblio.org> wrote: > Recently I've been looking at the javadoc:fix goal. The existing goal > is not particularly helpful. Take a look at > https://github.com/apache/maven-javadoc-plugin/pull/1249/files if > you'd like an example of what it currently does. They're some white > space changes and some added comments that look like this: > > /** > * <p>Constructor for AbstractFixJavadocMojo.</p> > * > * @param inputHandler a {@link > org.codehaus.plexus.components.interactivity.InputHandler} object > */ > > This really adds nothing to what the javadoc tool fills in by default. > At best it's placeholders that a human should go through and edit by > hand before committing. > > I'd like to consider if we should do something different with this > goal. I can think of three possibilities: > > 1. Remove it completely. It's pretty wonky, there are a few bugs I > haven't mentioned here, and it's a more than usually risky goal since > it actively modifies the user's source code. Maybe we'd be better off > without it. > > 2. Change what it does. In particular instead of generating new > Javadoc, fix the existing Javadoc to conform to the Oracle style > guidelines. I've been experimenting with code that would handle a lot > of capitalization, punctuation, and formatting problems. That might be > a useful ting to do and it's more in keeping with the name of the goal > as it fixes rather than creates. > > 3. Create genuinely useful doc comments that aren't rephrased method > names. The idea would be to hook into LLMs to analyze the code and > write the doc comments. This would enable the tool to describe what > methods do and what arguments are. Instead of > > > * @param inputHandler a {@link > org.codehaus.plexus.components.interactivity.InputHandler} object > > we could get something like > > * @param inputHandler the stream, reader or other source from > which the Java source code is read > > This would be the most ambitious change, but it does seem to be the > way the world is moving. > > These three options aren't mutually exclusive either. We could do 2 > and 3, or remove the existing goal and introduce #3 in a new > javadoc:generate goal. Thoughts? Preferences? > > > -- > Elliotte Rusty Harold > elh...@ibiblio.org > > --------------------------------------------------------------------- > To unsubscribe, e-mail: dev-unsubscr...@maven.apache.org > For additional commands, e-mail: dev-h...@maven.apache.org > >
