(maven-surefire) 01/01: javadoc: improve description of systemPropertyVariables

[kwin]

This is an automated email from the ASF dual-hosted git repository.

kwin pushed a commit to branch feature/improve-system-properties-javadoc
in repository https://gitbox.apache.org/repos/asf/maven-surefire.git

commit 7fc9e58fe20d66dc5a34d05b08a2cc6a06b5e9b1
Author: Konrad Windszus <k...@apache.org>
AuthorDate: Tue Jul 9 11:22:04 2024 +0200

    javadoc: improve description of systemPropertyVariables
    
    clarify order of precedence
---
 .../apache/maven/plugin/surefire/AbstractSurefireMojo.java  | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git 
a/maven-surefire-common/src/main/java/org/apache/maven/plugin/surefire/AbstractSurefireMojo.java
 
b/maven-surefire-common/src/main/java/org/apache/maven/plugin/surefire/AbstractSurefireMojo.java
index 4c98873fe..47d691a13 100644
--- 
a/maven-surefire-common/src/main/java/org/apache/maven/plugin/surefire/AbstractSurefireMojo.java
+++ 
b/maven-surefire-common/src/main/java/org/apache/maven/plugin/surefire/AbstractSurefireMojo.java
@@ -314,7 +314,8 @@ public abstract class AbstractSurefireMojo extends 
AbstractMojo implements Suref
     /**
      * List of System properties to pass to a provider.
      *
-     * @deprecated Use systemPropertyVariables instead.
+     * @deprecated Use {@link #systemPropertyVariables} instead.
+     * @see #systemPropertyVariables {@code systemPropertyVariables} for how 
the effective provider properties are calculated
      */
     @Deprecated
     @Parameter
@@ -322,8 +323,18 @@ public abstract class AbstractSurefireMojo extends 
AbstractMojo implements Suref
 
     /**
      * List of System properties to pass to a provider.
+     * The effective system properties given to a provider are contributed 
from several sources:
+     * <ol>
+     * <li>{@link #systemProperties}</li>
+     * <li>{@link AbstractSurefireMojo#getSystemPropertiesFile()} (set via 
parameter {@code systemPropertiesFile} on some goals)</li>
+     * <li>{@link #systemPropertyVariables}</li>
+     * <li>User properties from {@link MavenSession#getUserProperties()}, 
usually set via CLI options given with {@code -D}</li>
+     * </ol>
+     * Later sources may overwrite same named properties from earlier sources, 
that means for example that one cannot overwrite user properties with either
+     * {@link #systemProperties}, {@link 
AbstractSurefireMojo#getSystemPropertiesFile()} or {@link 
#systemPropertyVariables}.
      *
      * @since 2.5
+     * @see #systemProperties
      */
     @Parameter
     private Map<String, String> systemPropertyVariables;