SONAR-4865 Apply some feedback on issue location API

diff --git a/sonar-batch/src/main/java/org/sonar/batch/issue/DeprecatedIssueBuilderWrapper.java b/sonar-batch/src/main/java/org/sonar/batch/issue/DeprecatedIssueBuilderWrapper.java
index 146a40e06e31591aa1fd509cba1e8e158d665dbf..e3f416a9ef93c2bd549bfd808e8ce408b16b1836 100644 (file)
--- a/sonar-batch/src/main/java/org/sonar/batch/issue/DeprecatedIssueBuilderWrapper.java
+++ b/sonar-batch/src/main/java/org/sonar/batch/issue/DeprecatedIssueBuilderWrapper.java
@@ -90,8 +90,8 @@ public class DeprecatedIssueBuilderWrapper implements Issuable.IssueBuilder {
   }
 
   @Override
-  public IssueBuilder addExecutionFlow(NewIssueLocation... flow) {
-    newIssue.addExecutionFlow(flow);
+  public IssueBuilder addExecutionFlow(Iterable<NewIssueLocation> flowLocations) {
+    newIssue.addExecutionFlow(flowLocations);
     return this;
   }
 

diff --git a/sonar-core/src/main/java/org/sonar/core/issue/DefaultIssueBuilder.java b/sonar-core/src/main/java/org/sonar/core/issue/DefaultIssueBuilder.java
index 4a107e459489e7fd1bc61d18a30fc4cc73d87f6c..e65a71bab690988733c098cddb02662339f39e84 100644 (file)
--- a/sonar-core/src/main/java/org/sonar/core/issue/DefaultIssueBuilder.java
+++ b/sonar-core/src/main/java/org/sonar/core/issue/DefaultIssueBuilder.java
@@ -81,7 +81,7 @@ public class DefaultIssueBuilder implements Issuable.IssueBuilder {
   }
 
   @Override
-  public IssueBuilder addExecutionFlow(NewIssueLocation... flow) {
+  public IssueBuilder addExecutionFlow(Iterable<NewIssueLocation> flow) {
     throw unsupported();
   }
 

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 fb1f25bdcdf3940ef4c347f5f9a5ea3003f5c44f..ecf61d7cd642fc45b89b35e4574e1c71935a840a 100644 (file)
--- 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
@@ -115,31 +115,39 @@ public interface InputFile extends InputPath {
   boolean isEmpty();
 
   /**
-   * Return a {@link TextPointer} in the given file.
+   * Returns a {@link TextPointer} in the given file.
    * @param line Line of the pointer. Start at 1.
    * @param lineOffset Offset in the line. Start at 0.
    * @throw {@link IllegalArgumentException} if line or offset is not valid for the given file.
+   * @since 5.2
    */
   TextPointer newPointer(int line, int lineOffset);
 
   /**
-   * Return a {@link TextRange} in the given file.
+   * Returns a {@link TextRange} in the given file.
    * @param start start pointer
    * @param end end pointer
    * @throw {@link IllegalArgumentException} if start or stop pointers are not valid for the given file.
+   * @since 5.2
    */
   TextRange newRange(TextPointer start, TextPointer end);
 
   /**
-   * Return a {@link TextRange} in the given file.
+   * Returns a {@link TextRange} in the given file.
+   * <ul>
+   * <li><code>newRange(1, 0, 1, 1)</code> selects the first character at line 1</li>
+   * <li><code>newRange(1, 0, 1, 10)</code> selects the 10 first characters at line 1</li>
+   * </ul>
    * @throw {@link IllegalArgumentException} if start or stop positions are not valid for the given file.
+   * @since 5.2
    */
   TextRange newRange(int startLine, int startLineOffset, int endLine, int endLineOffset);
 
   /**
-   * Return a {@link TextRange} in the given file that select the full line.
+   * Returns a {@link TextRange} in the given file that select the full line.
    * @param line Start at 1.
    * @throw {@link IllegalArgumentException} if line is not valid for the given file.
+   * @since 5.2
    */
   TextRange selectLine(int line);
 }

diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/TextRange.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/TextRange.java
index 08239a1e0cdb4c68824936c213cdb06375b104f0..213c0060d2cc5df815f94f3cab943993e5492169 100644 (file)
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/TextRange.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/TextRange.java
@@ -20,7 +20,14 @@
 package org.sonar.api.batch.fs;
 
 /**
- * Represents a text range in an {@link InputFile}
+ * Represents a text range in an {@link InputFile}. 
+ * 
+ * A range is delimited by two {@link TextPointer}. 
+ * <ul>
+ * <li><code>TextRange(TextPointer(1, 0), TextPointer(1, 1))</code> represents the first character at line 1</li>
+ * <li><code>TextRange(TextPointer(1, 0), TextPointer(1, 10))</code> represents the 10 first characters at line 1</li>
+ * </ul>
+ * @see InputFile#newRange(int, int, int, int)
  *
  * @since 5.2
  */

diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/issue/NewIssue.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/issue/NewIssue.java
index 5ae14bcda20680b3ef947b3b569d0db7a9b055b5..c156c953136eb0096b07fdd276cce398d77d3049 100644 (file)
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/issue/NewIssue.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/issue/NewIssue.java
@@ -50,38 +50,33 @@ public interface NewIssue {
   NewIssue overrideSeverity(@Nullable Severity severity);
 
   /**
+   * Primary location for this issue.
    * @since 5.2
-   * Primary for this issue.
    */
   NewIssue at(NewIssueLocation primaryLocation);
 
   /**
-   * @since 5.2
    * Register an additional location for this issue.
-   */
-  NewIssue addLocation(NewIssueLocation location);
-
-  /**
    * @since 5.2
-   * Register an execution flow for this issue.
    */
-  NewIssue addExecutionFlow(NewIssueLocation... locations);
+  NewIssue addLocation(NewIssueLocation location);
 
   /**
+   * Register an execution flow for this issue. An execution flow is an ordered list of issue locations that help to understand the issue.
+   * It is usually the path leading to the primary location. Several execution flows can be registered.
    * @since 5.2
-   * Register an execution flow for this issue.
    */
-  NewIssue addExecutionFlow(Iterable<NewIssueLocation> locations);
+  NewIssue addExecutionFlow(Iterable<NewIssueLocation> flowLocations);
 
   /**
-   * @since 5.2
    * Create a new location for this issue. First registered location is considered as primary location.
+   * @since 5.2
    */
   NewIssueLocation newLocation();
 
   /**
-   * @since 5.2
    * Attach a new attribute to the issue. Not used by SQ but can be reused later for integration needs (for example it is returned by WS).
+   * @since 5.2
    */
   NewIssue addAttribute(String key, String value);
 

diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/issue/internal/DefaultIssue.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/issue/internal/DefaultIssue.java
index e4c3b73ba85dfda3311e41487452a05e01b3bdf2..1c623ee92f6dbc8c676e836c02dc38471e1e4645 100644 (file)
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/issue/internal/DefaultIssue.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/issue/internal/DefaultIssue.java
@@ -25,7 +25,6 @@ import com.google.common.collect.ImmutableList;
 import com.google.common.collect.ImmutableMap;
 import com.google.common.collect.Lists;
 import java.util.ArrayList;
-import java.util.Arrays;
 import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
@@ -109,11 +108,6 @@ public class DefaultIssue extends DefaultStorable implements Issue, NewIssue {
     return this;
   }
 
-  @Override
-  public DefaultIssue addExecutionFlow(NewIssueLocation... locations) {
-    return addExecutionFlow(Arrays.asList(locations));
-  }
-
   @Override
   public DefaultIssue addExecutionFlow(Iterable<NewIssueLocation> locations) {
     List<IssueLocation> flowAsList = new ArrayList<>();

diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/issue/Issuable.java b/sonar-plugin-api/src/main/java/org/sonar/api/issue/Issuable.java
index c2adf0e5e11934c24508b90c105c1f8b0f4ef0fb..fad75b15d2892d65dbfdabd8d0ffcba25e9b1459 100644 (file)
--- a/sonar-plugin-api/src/main/java/org/sonar/api/issue/Issuable.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/issue/Issuable.java
@@ -101,9 +101,10 @@ public interface Issuable extends Perspective {
 
     /**
      * @since 5.2
-     * Register an execution flow for this issue.
+     * Register an execution flow for this issue. An execution flow is an ordered list of issue locations that help to understand the issue.
+     * It is usually the path leading to the primary location. Several execution flows can be registered.
      */
-    IssueBuilder addExecutionFlow(NewIssueLocation... flow);
+    IssueBuilder addExecutionFlow(Iterable<NewIssueLocation> flowLocations);
 
     /**
      * Overrides the severity declared in Quality profile. Do not execute in standard use-cases.