gnodet commented on code in PR #1123:
URL:
https://github.com/apache/maven-compiler-plugin/pull/1123#discussion_r4086400342
##########
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 <i>not</i> 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. 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 most
configurations a change causes
+ * the whole module (all its source files) to be recompiled; see the
{@code sources} and
+ * {@code classes} values below, which decide whether only the modified
source files are recompiled
+ * or whether a change triggers a full rebuild. The plugin never performs
dependency-based
+ * compilation of only the directly or transitively affected classes.
+ *
Review Comment:
Two inaccuracies in this block need fixing:
1. **"in most configurations a change causes the whole module to be
recompiled"** — this is wrong for the default. The default
(`"options,dependencies,sources"`) recompiles **only the modified source
files** when a source changes. A full rebuild happens only when compiler
options or a JAR dependency changed — or when annotation processors are present
(Java < 23). This sentence will mislead v4 users.
2. **"The plugin never performs dependency-based compilation"** — too
absolute: the `modules` algorithm delegates the per-file recompilation decision
to `javac --module`, which does perform dependency-aware recompilation. The
existing `<h4>Limitations</h4>` section below is already accurate; rely on that
instead of a blanket "never".
```suggestion
* <b>Despite the word "incremental" in the name, this is <i>not</i> 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 change, or annotation
processor presence.
*
* <p>The algorithm to use for selecting which files to compile.
```
--
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]
