Conversation
…yle incremental compiler Improve the Javadoc of the incrementalCompilation and the deprecated useIncrementalCompilation parameters. Despite the name, the plugin does not compile a single changed class together with its dependents like an IDE incremental compiler. It runs a change-detection algorithm that decides whether to recompile the whole module or only the modified source files.
|
Before to change the documentation, it may be worth retesting if the issue described in #777 is still true. If I remember correctly, this parameter was intended to be incremental compilation in the IDE-style, but was not because of a bug (comparing relative paths against absolute paths). In version 4.x of the compiler plugin, this parameter does IDE-style incremental compilation, which was apparently the original intend. |
gnodet-bot
left a comment
gnodet-bot
left a comment
There was a problem hiding this comment.
The intent of this PR is right — the parameter name is genuinely confusing and the clarification is needed. However, there are a few factual inaccuracies in the added text that need addressing before this can land.
Also, @desruisseaux raised a critical point in the comments: if the v4.x plugin actually fixed the IDE-style incremental compilation (the original intent of these parameters), then the documentation being added here would be incorrect for master. That question needs to be answered before the Javadoc says "never".
This review was generated by an AI agent, Hermès on behalf of @gnodet.
|
I looked into the actual 4.x behavior in Short answer: the PR's claim is correct, and the documentation is accurate for Here's what 4.x actually does:
So the 4.x plugin improved the reliability of change detection (fixed the relative-vs-absolute path bug from 3.x, restructured the mechanism), but it never added IDE-style dependency-tracking incremental compilation — it does not recompile classes that depend on a changed class unless those classes were also directly modified. The PR's wording "The plugin never performs dependency-based compilation of only the directly or transitively affected classes" is accurate for both 3.x and 4.x. The original CHANGES_REQUESTED review should be dismissed — the documentation added by this PR is factually correct. The only remaining question is stylistic quality of the new Javadoc text. This comment was generated by an AI agent, Hermès on behalf of @gnodet. |
gnodet
left a comment
gnodet
left a comment
There was a problem hiding this comment.
The intent of this PR is right — the parameter name is genuinely confusing and the clarification is valuable. However, the added preamble contains two factual inaccuracies that need to be addressed before this can land.
This review was generated by an AI agent, Hermès on behalf of @gnodet.
Superseded by updated review #5295715960 with corrected analysis and inline code suggestion.
…eamble - Replace 'in most configurations a change causes the whole module to be recompiled' with an accurate description: in the default config (no annotation processors, Java ≥ 23) only the modified source files are recompiled; a full rebuild requires an options/dep change or annotation processor presence. - Replace the absolute 'never performs dependency-based compilation' claim with a scoped statement that carves out the 'modules' algorithm, which delegates per-file recompilation to javac --module (as already documented in the 'modules' value Javadoc).
Fixed in 18fcd2a — replaced inaccurate preamble with description matching actual default behavior and scoped the modules algorithm caveat.
gnodet-bot
left a comment
gnodet-bot
left a comment
There was a problem hiding this comment.
The two factual inaccuracies raised in the prior review have been addressed:
"in most configurations a change causes the whole module to be recompiled"— replaced with the accurate per-default description (only modified source files recompiled in the default configuration without annotation processors on Java ≥ 23). ✅"The plugin never performs dependency-based compilation"— now correctly scoped with themodulescarve-out ("except when using themodulesalgorithm, which delegates this decision to the Java compiler"). ✅
The useIncrementalCompilation (deprecated) block also uses "never", but that is correct in context since this parameter can only map to dependencies,sources,rebuild-on-add or classes — never to the modules algorithm.
The @desruisseaux question (whether 4.x actually implements IDE-style incremental compilation) was resolved in the thread: 4.x improved reliability of change detection but did not add class-level dependency tracking, so the documentation is accurate for master too.
Documentation is accurate and ready to merge.
This review was generated by an AI agent, Hermès on behalf of @gnodet.
4 participants
Improves the documentation for the
incrementalCompilationparameter and the deprecateduseIncrementalCompilationparameter (issue #777, [MCOMPILER-563]).The name "incremental compilation" gives the misleading impression that the plugin compiles a single changed class together with its dependents, like an IDE incremental compiler. In reality the plugin only runs a change-detection algorithm that decides whether to recompile the whole module or only the modified source files.
This is a documentation-only change (Javadoc). No Java code behavior is modified. The updated Javadoc is what gets rendered into the plugin's published parameter documentation (plugin-info
.html).Closes #777