desruisseaux commented on code in PR #1123:
URL:
https://github.com/apache/maven-compiler-plugin/pull/1123#discussion_r4506526008
##########
src/main/java/org/apache/maven/plugin/compiler/AbstractCompilerMojo.java:
##########
@@ -586,9 +586,19 @@ final Charset charset() {
protected String outputTimestamp;
/**
- * The algorithm to use for selecting which files to compile.
- * Values can be {@code dependencies}, {@code sources}, {@code classes},
{@code rebuild-on-change},
- * {@code rebuild-on-add}, {@code modules} or {@code none}.
+ * The strategy for selecting which files to compile.
+ * The value can be {@code dependencies}, {@code sources}, {@code
classes}, {@code rebuild-on-change},
+ * {@code rebuild-on-add}, {@code modules} or {@code none}.<p>
+ *
+ * <strong>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.
Review Comment:
This is not very important, but I try to keep each sentence on their own
line when the sentences are not too long or too short (otherwise I target some
natural boundary such as a coma). The reason is because changes in Git and
GitHub are handled on a line-by-line basis. When sentences are interleaved, a
change in one sentence appears as if two sentences where potentially modified.
We have to look more closely for identifying which sentence was modified.
So, above comment could be like below (exact same text, just reformatted and
replacing `<i>` by `<em>` since the intend was emphasis):
```java
* <strong>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 <em>detect
changes</em> 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 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]
