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
