SONAR-7612 Apply feedback

22 files changed, 56 insertions, 34 deletions

diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/AbstractCpdMapping.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/AbstractCpdMapping.java
index d644d00d5e3..8c6896f1bd3 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/AbstractCpdMapping.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/AbstractCpdMapping.java
@@ -26,7 +26,7 @@ import org.sonar.api.resources.Resource;
  * A pre-implementation of the CpdMapping extension point
  *
  * @since 1.10
- * @deprecated since 5.6
+ * @deprecated since 5.6 use {@link SensorContext#newCpdTokens()}
  */
 @Deprecated
 public abstract class AbstractCpdMapping implements CpdMapping {
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/DecoratorBarriers.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/DecoratorBarriers.java
index e05bbb2a9db..7f796294d39 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/DecoratorBarriers.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/DecoratorBarriers.java
@@ -28,7 +28,7 @@ package org.sonar.api.batch;
  * </ul>
  *
  * @since 2.3
- * @deprecated since 5.6 no more used since Decorators are deprecated
+ * @deprecated since 5.6 as {@link Decorator} is deprecated
  */
 @Deprecated
 public interface DecoratorBarriers {
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/DecoratorContext.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/DecoratorContext.java
index 2da3f35e3ba..cd5056c3882 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/DecoratorContext.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/DecoratorContext.java
@@ -30,7 +30,7 @@ import org.sonar.api.resources.Resource;
 
 /**
  * @since 1.10
- * @deprecated since 5.6 no more used since Decorator is deprecated
+ * @deprecated since 5.6 as {@link Decorator} is deprecated
  */
 @Deprecated
 public interface DecoratorContext {
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/PostJob.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/PostJob.java
index 5605a34c305..a7120f5e8e8 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/PostJob.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/PostJob.java
@@ -29,7 +29,7 @@ import org.sonar.api.resources.Project;
  * it is an asynchronous processing on server side.
  *
  * @since 1.10
- * @deprecated since 5.6 use {@link org.sonar.api.batch.postjob.PostJob}
+ * @deprecated since 5.6 use org.sonar.api.batch.postjob.PostJob
  */
 @Deprecated
 @BatchSide
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/Sensor.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/Sensor.java
index ebe26fdb6d9..5f632e974a9 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/Sensor.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/Sensor.java
@@ -40,7 +40,7 @@ import org.sonar.api.resources.Project;
  * 
  *
  * @since 1.10
- * @deprecated since 5.6 use {@link org.sonar.api.batch.sensor.Sensor}
+ * @deprecated since 5.6 use org.sonar.api.batch.sensor.Sensor
  */
 @Deprecated
 @BatchSide
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/InputComponent.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/InputComponent.java
index 8bf224613ef..961156d56c0 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/InputComponent.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/InputComponent.java
@@ -25,6 +25,7 @@ package org.sonar.api.batch.fs;
  * @since 5.2
  * @see InputFile
  * @see InputDir
+ * @see InputModule
  */
 public interface InputComponent {
 
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/InputDir.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/InputDir.java
index 9237df36547..98bf6dcedae 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/InputDir.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/InputDir.java
@@ -23,7 +23,7 @@ import java.io.File;
 import java.nio.file.Path;
 
 /**
- * Layer over {@link java.io.File} for directories.
+ * Layer over {@link java.io.File} for directories. You can access InputDir using {@link FileSystem#inputDir(File)}.
  *
  * @since 4.5
  */
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/InputModule.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/InputModule.java
index cdae78da70e..78902475cd5 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/InputModule.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/InputModule.java
@@ -19,8 +19,10 @@
  */
 package org.sonar.api.batch.fs;
 
+import org.sonar.api.batch.sensor.SensorContext;
+
 /**
- * Used to create issues and measures on modules.
+ * Used to create issues and measures on modules. You can access InputModule using {@link SensorContext#module()}
  *
  * @since 5.2
  */
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/postjob/PostJobContext.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/postjob/PostJobContext.java
index ed9706309bb..df593e96db3 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/postjob/PostJobContext.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/postjob/PostJobContext.java
@@ -19,6 +19,7 @@
  */
 package org.sonar.api.batch.postjob;
 
+import org.sonar.api.batch.AnalysisMode;
 import org.sonar.api.batch.postjob.issue.PostJobIssue;
 import org.sonar.api.config.Settings;
 
@@ -33,15 +34,19 @@ public interface PostJobContext {
    */
   Settings settings();
 
+  AnalysisMode analysisMode();
+
   // ----------- Only available in preview mode --------------
 
   /**
-   * All the unresolved issues of the project, including the issues reported by end-users.
+   * All the unresolved issues of the project, including the issues reported by end-users. Only available in preview/issues mode.
+   * @throw {@link UnsupportedOperationException} if not in preview/issues mode. To test the mode you can use {@link #analysisMode()}.
    */
   Iterable<PostJobIssue> issues();
 
   /**
-   * All the issues of this project that have been marked as resolved during this scan
+   * All the issues of this project that have been marked as resolved during this scan. Only available in preview/issues mode.
+   * @throw {@link UnsupportedOperationException} if not in preview mode. To test the mode you can use {@link #analysisMode()}.
    */
   Iterable<PostJobIssue> resolvedIssues();
 
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/postjob/issue/PostJobIssue.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/postjob/issue/PostJobIssue.java
index 553e12826a9..67a10970e9a 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/postjob/issue/PostJobIssue.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/postjob/issue/PostJobIssue.java
@@ -25,7 +25,7 @@ import org.sonar.api.batch.rule.Severity;
 import org.sonar.api.rule.RuleKey;
 
 /**
- * Represents an issue state at the end of the batch analysis. Some attributes are only available in preview/issues mode.
+ * Represents an issue state at the end of the scanner analysis in preview/issues mode.
  *
  * @since 5.2
  */
@@ -66,12 +66,12 @@ public interface PostJobIssue {
   String message();
 
   /**
-   * Severity.  Only accurate in preview/issues mode.
+   * Severity.
    */
   Severity severity();
 
   /**
-   * If the issue a new one. Only available in preview/issues mode.
+   * If the issue a new one.
    */
   boolean isNew();
 
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/component/RubyComponentService.java b/sonar-plugin-api/src/main/java/org/sonar/api/component/RubyComponentService.java
index 0f4f3e2ca5b..d38076c14dd 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/component/RubyComponentService.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/component/RubyComponentService.java
@@ -24,9 +24,7 @@ import org.sonar.api.server.ServerSide;
 
 /**
  * @since 3.6
- * @deprecated since 5.6
  */
-@Deprecated
 @ServerSide
 public interface RubyComponentService {
 
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/resources/Directory.java b/sonar-plugin-api/src/main/java/org/sonar/api/resources/Directory.java
index ddcee47af4f..eb89b3bc3f7 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/resources/Directory.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/resources/Directory.java
@@ -23,12 +23,13 @@ import javax.annotation.CheckForNull;
 import org.apache.commons.lang.StringUtils;
 import org.apache.commons.lang.builder.ToStringBuilder;
 import org.sonar.api.batch.fs.FileSystem;
+import org.sonar.api.batch.fs.InputDir;
 import org.sonar.api.scan.filesystem.PathResolver;
 import org.sonar.api.utils.WildcardPattern;
 
 /**
  * @since 1.10
- * @deprecated since 5.6 should not be used in any API
+ * @deprecated since 5.6 replaced by {@link InputDir}.
  */
 @Deprecated
 public class Directory extends Resource {
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/resources/File.java b/sonar-plugin-api/src/main/java/org/sonar/api/resources/File.java
index 9ed3f16e4e1..8ce94861a68 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/resources/File.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/resources/File.java
@@ -25,14 +25,13 @@ import org.apache.commons.lang.StringUtils;
 import org.apache.commons.lang.builder.ToStringBuilder;
 import org.sonar.api.batch.SensorContext;
 import org.sonar.api.batch.fs.FileSystem;
+import org.sonar.api.batch.fs.InputFile;
 import org.sonar.api.scan.filesystem.PathResolver;
 import org.sonar.api.utils.WildcardPattern;
 
 /**
- * This class is an implementation of a resource of type FILE
- *
  * @since 1.10
- * @deprecated since 5.6 should not be used in any API
+ * @deprecated since 5.6 replaced by {@link InputFile}.
  */
 @Deprecated
 public class File extends Resource {
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/resources/Project.java b/sonar-plugin-api/src/main/java/org/sonar/api/resources/Project.java
index be1eacc08be..238084692a2 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/resources/Project.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/resources/Project.java
@@ -27,14 +27,13 @@ import javax.annotation.Nullable;
 import org.apache.commons.lang.StringUtils;
 import org.apache.commons.lang.builder.ToStringBuilder;
 import org.sonar.api.CoreProperties;
+import org.sonar.api.batch.fs.InputModule;
 import org.sonar.api.component.Component;
 import org.sonar.api.config.Settings;
 
 /**
- * A class that manipulates Projects in the Sonar way.
- *
  * @since 1.10
- * @deprecated since 5.6 should not be used in any API
+ * @deprecated since 5.6 replaced by {@link InputModule}.
  */
 @Deprecated
 public class Project extends Resource implements Component {
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/resources/Resource.java b/sonar-plugin-api/src/main/java/org/sonar/api/resources/Resource.java
index f2f5e5c49a7..fa9447168b3 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/resources/Resource.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/resources/Resource.java
@@ -23,12 +23,11 @@ import java.io.Serializable;
 import javax.annotation.CheckForNull;
 import javax.annotation.Nullable;
 import org.apache.commons.lang.StringUtils;
+import org.sonar.api.batch.fs.InputComponent;
 
 /**
- * The interface to implement to create a resource in Sonar
- *
  * @since 1.10
- * @deprecated since 5.6 should not be used in any API
+ * @deprecated since 5.6 replaced by {@link InputComponent}
  */
 @Deprecated
 public abstract class Resource implements Serializable {
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/resources/ResourceUtils.java b/sonar-plugin-api/src/main/java/org/sonar/api/resources/ResourceUtils.java
index 3344370abf4..8373a5f89a1 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/resources/ResourceUtils.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/resources/ResourceUtils.java
@@ -23,7 +23,7 @@ import org.apache.commons.lang.StringUtils;
 
 /**
  * @since 1.10
- * @deprecated since 5.6 should not be used in any API
+ * @deprecated since 5.6 as {@link Resource} is deprecated
  */
 @Deprecated
 public final class ResourceUtils {
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/test/CoverageBlock.java b/sonar-plugin-api/src/main/java/org/sonar/api/test/CoverageBlock.java
index dfb42a667dc..7f489e67265 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/test/CoverageBlock.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/test/CoverageBlock.java
@@ -22,7 +22,7 @@ package org.sonar.api.test;
 import java.util.List;
 
 /**
- * @deprecated since 5.6 feature will be removed soon
+ * @deprecated since 5.6. Feature will be removed without any alternatives.
  */
 @Deprecated
 public interface CoverageBlock {
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/test/MutableTestCase.java b/sonar-plugin-api/src/main/java/org/sonar/api/test/MutableTestCase.java
index bd90d2f0e53..4a8063cbda5 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/test/MutableTestCase.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/test/MutableTestCase.java
@@ -24,7 +24,7 @@ import javax.annotation.Nullable;
 import org.sonar.api.batch.fs.InputFile;
 
 /**
- * @deprecated since 5.6 feature will be removed soon
+ * @deprecated since 5.6. Feature will be removed without any alternatives.
  */
 @Deprecated
 public interface MutableTestCase extends TestCase {
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/test/MutableTestPlan.java b/sonar-plugin-api/src/main/java/org/sonar/api/test/MutableTestPlan.java
index 40829397558..71651876b63 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/test/MutableTestPlan.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/test/MutableTestPlan.java
@@ -20,7 +20,7 @@
 package org.sonar.api.test;
 
 /**
- * @deprecated since 5.6 feature will be removed soon
+ * @deprecated since 5.6. Feature will be removed without any alternatives.
  */
 @Deprecated
 public interface MutableTestPlan extends TestPlan<MutableTestCase> {
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/test/MutableTestable.java b/sonar-plugin-api/src/main/java/org/sonar/api/test/MutableTestable.java
index 525acfd568e..a0f02a7a597 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/test/MutableTestable.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/test/MutableTestable.java
@@ -20,7 +20,7 @@
 package org.sonar.api.test;
 
 /**
- * @deprecated since 5.6 feature will be removed soon
+ * @deprecated since 5.6. Feature will be removed without any alternatives.
  */
 @Deprecated
 public interface MutableTestable extends Testable {
diff --git a/sonar-scanner-engine/src/main/java/org/sonar/batch/postjob/DefaultPostJobContext.java b/sonar-scanner-engine/src/main/java/org/sonar/batch/postjob/DefaultPostJobContext.java
index 341bc7991a8..1e66067fded 100644
--- a/sonar-scanner-engine/src/main/java/org/sonar/batch/postjob/DefaultPostJobContext.java
+++ b/sonar-scanner-engine/src/main/java/org/sonar/batch/postjob/DefaultPostJobContext.java
@@ -23,6 +23,7 @@ import com.google.common.base.Function;
 import com.google.common.base.Predicate;
 import com.google.common.collect.Iterables;
 import javax.annotation.Nullable;
+import org.sonar.api.batch.AnalysisMode;
 import org.sonar.api.batch.fs.InputComponent;
 import org.sonar.api.batch.postjob.PostJobContext;
 import org.sonar.api.batch.postjob.issue.PostJobIssue;
@@ -39,11 +40,13 @@ public class DefaultPostJobContext implements PostJobContext {
   private final Settings settings;
   private final IssueCache cache;
   private final BatchComponentCache resourceCache;
+  private final AnalysisMode analysisMode;
 
-  public DefaultPostJobContext(Settings settings, IssueCache cache, BatchComponentCache resourceCache) {
+  public DefaultPostJobContext(Settings settings, IssueCache cache, BatchComponentCache resourceCache, AnalysisMode analysisMode) {
     this.settings = settings;
     this.cache = cache;
     this.resourceCache = resourceCache;
+    this.analysisMode = analysisMode;
   }
 
   @Override
@@ -52,12 +55,23 @@ public class DefaultPostJobContext implements PostJobContext {
   }
 
   @Override
+  public AnalysisMode analysisMode() {
+    return analysisMode;
+  }
+
+  @Override
   public Iterable<PostJobIssue> issues() {
+    if (!analysisMode.isIssues()) {
+      throw new UnsupportedOperationException("Issues are only available to PostJobs in 'issues' mode.");
+    }
     return Iterables.transform(Iterables.filter(cache.all(), new ResolvedPredicate(false)), new IssueTransformer());
   }
 
   @Override
   public Iterable<PostJobIssue> resolvedIssues() {
+    if (!analysisMode.isIssues()) {
+      throw new UnsupportedOperationException("Resolved issues are only available to PostJobs in 'issues' mode.");
+    }
     return Iterables.transform(Iterables.filter(cache.all(), new ResolvedPredicate(true)), new IssueTransformer());
   }
 
@@ -102,8 +116,7 @@ public class DefaultPostJobContext implements PostJobContext {
 
     @Override
     public Severity severity() {
-      String severity = wrapped.severity();
-      return severity != null ? Severity.valueOf(severity) : null;
+      return Severity.valueOf(wrapped.severity());
     }
 
     @Override
diff --git a/sonar-scanner-engine/src/test/java/org/sonar/batch/postjob/DefaultPostJobContextTest.java b/sonar-scanner-engine/src/test/java/org/sonar/batch/postjob/DefaultPostJobContextTest.java
index 5f9916919ec..803b6177eb7 100644
--- a/sonar-scanner-engine/src/test/java/org/sonar/batch/postjob/DefaultPostJobContextTest.java
+++ b/sonar-scanner-engine/src/test/java/org/sonar/batch/postjob/DefaultPostJobContextTest.java
@@ -22,6 +22,7 @@ package org.sonar.batch.postjob;
 import java.util.Arrays;
 import org.junit.Before;
 import org.junit.Test;
+import org.sonar.api.batch.AnalysisMode;
 import org.sonar.api.batch.fs.InputFile;
 import org.sonar.api.batch.postjob.issue.PostJobIssue;
 import org.sonar.api.batch.rule.Severity;
@@ -41,17 +42,21 @@ public class DefaultPostJobContextTest {
   private BatchComponentCache resourceCache;
   private DefaultPostJobContext context;
   private Settings settings;
+  private AnalysisMode analysisMode;
 
   @Before
   public void prepare() {
     issueCache = mock(IssueCache.class);
     resourceCache = new BatchComponentCache();
     settings = new Settings();
-    context = new DefaultPostJobContext(settings, issueCache, resourceCache);
+    analysisMode = mock(AnalysisMode.class);
+    context = new DefaultPostJobContext(settings, issueCache, resourceCache, analysisMode);
   }
 
   @Test
-  public void test() {
+  public void testIssues() {
+    when(analysisMode.isIssues()).thenReturn(true);
+
     assertThat(context.settings()).isSameAs(settings);
 
     TrackedIssue defaultIssue = new TrackedIssue();