gnodet commented on code in PR #1123:
URL:
https://github.com/apache/maven-compiler-plugin/pull/1123#discussion_r4126156397
##########
src/main/java/org/apache/maven/plugin/compiler/AbstractCompilerMojo.java:
##########
@@ -586,7 +586,16 @@ final Charset charset() {
protected String outputTimestamp;
/**
- * The algorithm to use for selecting which files to compile.
+ * <b>Despite the word "incremental" in the name, this is <em>not</em> an
incremental compiler
+ * in the sense of an IDE.</b> The plugin does not compile a single
changed class and the classes
+ * that depend on it (except when using the {@code modules} algorithm,
which delegates this decision
+ * to the Java compiler). It selects an algorithm used to <i>detect
changes</i> and to decide whether
+ * to recompile the whole module or only some source files. In the default
configuration (no annotation
+ * processors, Java ≥ 23), only the modified source files are
recompiled; a full rebuild is triggered
+ * by a compiler option change, a dependency JAR change, or annotation
processor presence; see the
+ * values and the Default value section below.
Review Comment:
Agreed on all counts. Here is the proposed replacement that adopts your
suggested wording:
```suggestion
* <strong>Despite the word "incremental" in the name, this is not yet
as reliable as the incremental
* compilation provided by some IDEs.</strong> It provides an
approximation based on the timestamps of
* source files. The current algorithms detect only direct changes —
recompiling only modified source files —
* but a future version may add an option for tracking classes that
depend on a modified class, as done by
* some IDEs. It selects a strategy to <i>detect changes</i> and decide
whether
* to recompile the whole sub-project or only some source files. In the
default configuration (no annotation
* processors, Java ≥ 23), only the modified source files are
recompiled. A full rebuild is triggered
* by a compiler option change, a dependency JAR change, or annotation
processor presence. See the
* values and the Default value section below.
```
This adopts your proposed nuance ("not yet as reliable" instead of "not an
IDE compiler"), adds the forward-looking note about potential future dependency
tracking you asked for, and replaces "module" with "sub-project" to avoid JPMS
ambiguity.
_This comment was generated by an AI agent, Hermès on behalf of
[@gnodet](https://github.com/gnodet)._
##########
src/main/java/org/apache/maven/plugin/compiler/AbstractCompilerMojo.java:
##########
@@ -670,7 +679,11 @@ final Charset charset() {
protected String incrementalCompilation;
/**
- * Whether to enable/disable incremental compilation feature.
+ * Whether to enable/disable the change detection that decides when to
recompile the module.
Review Comment:
Done — see the proposed replacement below. Also applied consistently to the
`incrementalCompilation` block above ("recompile the whole sub-project").
```suggestion
* Whether to enable/disable the change detection that decides when to
recompile the sub-project.
* Despite the word "incremental", this does not yet provide the same
reliability as the incremental
* compilation provided by some IDEs. It only detects changes based on
timestamps and, depending on
* the configuration, recompiles the whole sub-project or only the
modified source files.
```
This also removes the "never compiles a single changed class" sentence (too
absolute for a deprecated parameter, and redundant since the behaviour is fully
described by the `@deprecated` javadoc below it).
_This comment was generated by an AI agent, Hermès on behalf of
[@gnodet](https://github.com/gnodet)._
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
