From f28b97ccf8e36a706bee341d32596702f4e8ebf5 Mon Sep 17 00:00:00 2001
From: Duarte Meneses <duarte.meneses@sonarsource.com>
Date: Thu, 13 Aug 2020 14:04:35 -0500
Subject: [PATCH] SONAR-12897 Document in Javadoc use of sonar-plugin-api-impl
 for testing

---
 sonar-plugin-api/src/main/java/org/sonar/api/Plugin.java        | 1 +
 sonar-plugin-api/src/main/java/org/sonar/api/SonarRuntime.java  | 2 +-
 .../src/main/java/org/sonar/api/batch/fs/FileSystem.java        | 2 +-
 .../src/main/java/org/sonar/api/batch/fs/InputFile.java         | 2 +-
 .../src/main/java/org/sonar/api/batch/rule/ActiveRules.java     | 2 +-
 .../src/main/java/org/sonar/api/batch/sensor/Sensor.java        | 2 +-
 .../src/main/java/org/sonar/api/batch/sensor/SensorContext.java | 2 +-
 7 files changed, 7 insertions(+), 6 deletions(-)

diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/Plugin.java b/sonar-plugin-api/src/main/java/org/sonar/api/Plugin.java
index abe7ae3117b..ef882273579 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/Plugin.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/Plugin.java
@@ -69,6 +69,7 @@ import static java.util.Objects.requireNonNull;
  * </pre>
  *
  * <p>Example of Test
+ * Add a test dependency to sonar-plugin-api-impl to have access to implementation classes in tests.
  * <pre>
  *{@literal @}Test
  * public void test_plugin_extensions_compatible_with_5_6() {
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/SonarRuntime.java b/sonar-plugin-api/src/main/java/org/sonar/api/SonarRuntime.java
index 2ac1e54bd30..c7c717b86f1 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/SonarRuntime.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/SonarRuntime.java
@@ -133,7 +133,7 @@ import org.sonarsource.api.sonarlint.SonarLintSide;
  * </p>
  *
  * <p>
- * Unit tests of plugin extensions can create instances of {@link SonarRuntime}
+ * Unit tests of plugin extensions can add a test dependency to available in sonar-plugin-api-impl and create instances of {@link SonarRuntime}
  * via {@link org.sonar.api.internal.SonarRuntimeImpl}.
  * </p>
  *
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/FileSystem.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/FileSystem.java
index ee9a2b21f5f..bfecca4b0c3 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/FileSystem.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/FileSystem.java
@@ -41,7 +41,7 @@ import org.sonar.api.scanner.ScannerSide;
  * </pre>
  *
  * <h2>How to use in unit tests</h2>
- * The unit tests needing an instance of FileSystem can use the implementation
+ * The unit tests needing an instance of FileSystem can use the implementation, available in sonar-plugin-api-impl,
  * {@link org.sonar.api.batch.fs.internal.DefaultFileSystem} and the related {@link org.sonar.api.batch.fs.internal.DefaultInputFile},
  * for example :
  * <pre>
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/InputFile.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/InputFile.java
index abd4556a159..78e2a3702d9 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/InputFile.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/InputFile.java
@@ -29,7 +29,7 @@ import org.sonar.api.batch.sensor.SensorDescriptor;
 
 /**
  * This layer over {@link java.io.File} adds information for code analyzers.
- * For unit testing purpose, use TestInputFileBuilder and initialize
+ * For unit testing purpose, use TestInputFileBuilder available in sonar-plugin-api-impl and initialize
  * the needed fields:
  * 
  * <pre>
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/rule/ActiveRules.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/rule/ActiveRules.java
index afcd20f0e63..ba56e73be87 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/rule/ActiveRules.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/rule/ActiveRules.java
@@ -31,7 +31,7 @@ import java.util.Collection;
  * The rules that are activated on the current project. Quality profiles are
  * merged, so rules can relate to different repositories and languages.
  * <br>
- * Use {@link org.sonar.api.batch.rule.internal.ActiveRulesBuilder} to instantiate
+ * Use {@link org.sonar.api.batch.rule.internal.ActiveRulesBuilder} available in sonar-plugin-api-impl to instantiate
  * this component in unit tests.
  *
  * @since 4.2
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/Sensor.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/Sensor.java
index be123215511..41905ed6502 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/Sensor.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/Sensor.java
@@ -32,7 +32,7 @@ import org.sonarsource.api.sonarlint.SonarLintSide;
  * <p>
  * For example the Cobertura Sensor parses Cobertura report and saves the first-level of measures on files.
  * 
- * For testing purpose you can use SensorContextTester
+ * For testing purpose you can use SensorContextTester, available in sonar-plugin-api-impl
  * @since 5.1
  * @since 7.6 use {@link ProjectSensor} instead to make your Sensor run only once per analysis, and no more once per module
  */
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/SensorContext.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/SensorContext.java
index b156d2c5480..a387d51ea90 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/SensorContext.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/SensorContext.java
@@ -47,7 +47,7 @@ import org.sonar.api.utils.Version;
 
 /**
  * See {@link Sensor#execute(SensorContext)}
- * In order to write unit tests you can use SensorContextTester
+ * In order to write unit tests you can use SensorContextTester, available in sonar-plugin-api-impl
  * @since 5.1
  */
 public interface SensorContext {
-- 
2.39.5