gnodet-bot commented on code in PR #1120: URL: https://github.com/apache/maven-compiler-plugin/pull/1120#discussion_r4087175287
########## src/site/markdown/examples/compile-using-different-jdk.md: ########## @@ -21,29 +21,33 @@ under the License. ## Using Maven Toolchains -The preferable way to use a different JDK is to use the toolchains mechanism. -During the build of a project, Maven, without toolchains, will use the JDK to perform various steps, -like compiling the Java sources, generate the Javadoc, run unit tests or sign JARs. -Each of those plugins need a tool of the JDK to operate: `javac`, `javadoc`, `jarsigner`, etc. -A toolchain is a way to specify the path to the JDK to use for all of those plugins in a centralized manner, -independent from the one running Maven itself. +Maven is itself a Java application running in a JDK. +By default the same JDK that runs Maven builds the code and runs the tests. Review Comment: 🔴 **Missing comma after introductory adverb phrase.** "By default the same JDK..." is missing a comma after the introductory phrase "By default". ```suggestion By default, the same JDK that runs Maven builds the code and runs the tests. ``` ########## src/site/markdown/examples/compile-using-different-jdk.md: ########## @@ -21,29 +21,33 @@ under the License. ## Using Maven Toolchains -The preferable way to use a different JDK is to use the toolchains mechanism. -During the build of a project, Maven, without toolchains, will use the JDK to perform various steps, -like compiling the Java sources, generate the Javadoc, run unit tests or sign JARs. -Each of those plugins need a tool of the JDK to operate: `javac`, `javadoc`, `jarsigner`, etc. -A toolchain is a way to specify the path to the JDK to use for all of those plugins in a centralized manner, -independent from the one running Maven itself. +Maven is itself a Java application running in a JDK. +By default the same JDK that runs Maven builds the code and runs the tests. +However, sometimes you need different JDKs. For instance, recent versions of Maven require +Java 17 to run, but you might need to compile a project with Java 8. Review Comment: 🔴 **Banned modal `might` retained — contradicts the PR's own STE100 goal.** The PR description explicitly lists `might` in the banned modals removed. Use `can` or restructure to a factual statement. ```suggestion Java 17 to run, but you can use Java 8 to compile a project. ``` ########## src/site/markdown/examples/compile-using-different-jdk.md: ########## @@ -21,29 +21,33 @@ under the License. ## Using Maven Toolchains -The preferable way to use a different JDK is to use the toolchains mechanism. -During the build of a project, Maven, without toolchains, will use the JDK to perform various steps, -like compiling the Java sources, generate the Javadoc, run unit tests or sign JARs. -Each of those plugins need a tool of the JDK to operate: `javac`, `javadoc`, `jarsigner`, etc. -A toolchain is a way to specify the path to the JDK to use for all of those plugins in a centralized manner, -independent from the one running Maven itself. +Maven is itself a Java application running in a JDK. +By default the same JDK that runs Maven builds the code and runs the tests. +However, sometimes you need different JDKs. For instance, recent versions of Maven require +Java 17 to run, but you might need to compile a project with Java 8. +Toolchains are the preferred way to use different JDKs to run Maven and to build the project. -To set this up, refer to the [Guide to Using Toolchains](https://maven.apache.org/guides/mini/guide-using-toolchains.html), -which makes use of the [Maven Toolchains Plugin](https://maven.apache.org/plugins/maven-toolchains-plugin/). +During the build, Maven uses the JDK to perform various steps. +These steps include compiling the Java sources, generating the Javadoc, running unit tests, signing JARs, and more. +Most core Maven plugins execute a JDK tool: `javac`, `javadoc`, `jarsigner`, etc. +A toolchain specifies the path to the JDK where the plugin finds these tools. +It is independent of the JDK that runs Maven itself. -With the maven-toolchains-plugin you configure 1 default JDK toolchain for all related maven-plugins. -Since maven-compiler-plugin 3.6.0 when using with Maven 3.3.1+ it is also possible to give the plugin its own toolchain, -which can be useful in case of different JDK calls per execution block -(e.g. the test sources require a different compiler compared to the main sources). +To set this up, refer to the [Guide to Using Toolchains](https://maven.apache.org/guides/mini/guide-using-toolchains.html) +and the [Maven Toolchains Plugin](https://maven.apache.org/plugins/maven-toolchains-plugin/). + +With the maven-toolchains-plugin, you configure one default JDK toolchain for all related Maven plugins. +Since maven-compiler-plugin 3.6.0, it is also possible to assign different plugins different toolchains. +For example, the test sources might require Java 8 but compilation requires Java 11. Review Comment: 🔴 **Banned modal `might` retained — same STE100 violation.** Use a factual example instead. ```suggestion For example, the test sources can require Java 8 while compilation requires Java 11. ``` ########## src/site/markdown/examples/jpms_args.md: ########## @@ -20,26 +20,26 @@ under the License. # Arguments related to Java Platform Module System Java 9 comes with a new set of arguments related to the Java Platform Modular System (JPMS). -Besides the module path there are other new arguments which can change the behavior of the application. +Besides the module path, there are other new arguments which can change the behavior of the application. These can be used during both compile time and runtime. -Except the module path, these extra arguments should not be needed for compilation and execution of the main code -(if they are needed, then maybe the `module-info.java` file is incomplete). -But they may be needed for compilation and execution of tests. -In such case, at runtime it is useful to know which extra arguments were used at compile time. +Except the module path, these extra arguments are not needed for compilation and execution of the main code. +If they are needed, then the `module-info.java` file can be incomplete. Review Comment: ⚠️ **Semantic distortion: `can be incomplete` changes the meaning.** Original: _"maybe the `module-info.java` file is incomplete"_ — a design observation suggesting the file might be missing declarations. New: _"the `module-info.java` file can be incomplete"_ — reads as a general factual capability statement, not the intended design warning. Suggest preserving the original intent: ```suggestion If they are needed, then the `module-info.java` file is probably incomplete. ``` -- 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]
