+1 (nb) for removing
Am 01.09.2025 um 13:16 schrieb Olivier Lamy:
Hi,
Thanks for looking into this.
I would remove this mojo.
You can do this easily and better these days using any AI coding agent.
I have already bumped the next version to 3.12.0 as there is already a
breaking change
https://github.com/apache/maven-javadoc-plugin/pull/1259
So we can add a new one.
I would like to do a new release, maybe by the end of this week.
cheers
Olivier
On Mon, 1 Sept 2025 at 20: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
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@maven.apache.org
For additional commands, e-mail: dev-h...@maven.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@maven.apache.org
For additional commands, e-mail: dev-h...@maven.apache.org
