javadoc: improve description of systemPropertyVariables

maven-failsafe-plugin/src/main/java/org/apache/maven/plugin/failsafe/IntegrationTestMojo.java

@@ -525,6 +525,11 @@ public class IntegrationTestMojo extends AbstractSurefireMojo {
     @Parameter(property = "failsafe.enableProcessChecker")
     private String enableProcessChecker;
 
+    /**
+     * Properties file being used as system properties passed to the provider.
+     *
+     * @see AbstractSurefireMojo#systemPropertyVariables {@code systemPropertyVariables} for how the effective provider properties are calculated
+     */
     @Parameter(property = "failsafe.systemPropertiesFile")
     private File systemPropertiesFile;
 

maven-surefire-common/src/main/java/org/apache/maven/plugin/surefire/AbstractSurefireMojo.java

@@ -314,16 +314,27 @@ 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
     private Properties systemProperties;
 
     /**
      * 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;

maven-surefire-plugin/src/main/java/org/apache/maven/plugin/surefire/SurefirePlugin.java

@@ -502,6 +502,11 @@ public class SurefirePlugin extends AbstractSurefireMojo implements SurefireRepo
     @Parameter(property = "surefire.enableProcessChecker")
     private String enableProcessChecker;
 
+    /**
+     * Properties file being used as system properties passed to the provider.
+     *
+     * @see AbstractSurefireMojo#systemPropertyVariables {@code systemPropertyVariables} for how the effective provider properties are calculated
+     */
     @Parameter(property = "surefire.systemPropertiesFile")
     private File systemPropertiesFile;