SONAR-3755 improve documentation

11 files changed, 93 insertions, 23 deletions

diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/issue/Issue.java b/sonar-plugin-api/src/main/java/org/sonar/api/issue/Issue.java
index 982ed14ff94..77d92abed4f 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/issue/Issue.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/issue/Issue.java
@@ -83,6 +83,9 @@ public interface Issue extends Serializable {
   @CheckForNull
   String message();
 
+  /**
+   * Optional line number. If set, then it's greater than or equal 1.
+   */
   @CheckForNull
   Integer line();
 
@@ -99,17 +102,26 @@ public interface Issue extends Serializable {
   @CheckForNull
   Double effortToFix();
 
+  /**
+   * See constant values in {@link Issue}.
+   */
   String status();
 
   /**
-   * The type of resolution, or null if the issue is not resolved.
+   * The type of resolution, or null if the issue is not resolved. See constant values in {@link Issue}.
    */
   @CheckForNull
   String resolution();
 
+  /**
+   * Login of the user who reported this issue. Null if the issue is reported by a rule engine.
+   */
   @CheckForNull
   String reporter();
 
+  /**
+   * Login of the user who is assigned to this issue. Null if the issue is not assigned.
+   */
   @CheckForNull
   String assignee();
 
@@ -117,6 +129,9 @@ public interface Issue extends Serializable {
 
   Date updateDate();
 
+  /**
+   * Date when status was set to {@link Issue#STATUS_CLOSED}, else null.
+   */
   @CheckForNull
   Date closeDate();
 
@@ -125,6 +140,10 @@ public interface Issue extends Serializable {
 
   Map<String, String> attributes();
 
+  /**
+   * Login of the SCM account that introduced this issue. Requires the
+   * <a href="http://www.sonarsource.com/products/plugins/developer-tools/developer-cockpit/">Developer Cockpit Plugin</a> to be installed.
+   */
   @CheckForNull
   String authorLogin();
 
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/issue/IssueQueryResult.java b/sonar-plugin-api/src/main/java/org/sonar/api/issue/IssueQueryResult.java
index 4caa572140a..6dedb9e5ab7 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/issue/IssueQueryResult.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/issue/IssueQueryResult.java
@@ -33,14 +33,20 @@ import java.util.List;
  * @since 3.6
  */
 public interface IssueQueryResult {
+  /**
+   * Non-null paginated list of issues.
+   */
   List<Issue> issues();
 
   /**
-   * Return first issue in the list.
-   * It will throws IllegalArgumentException if no issue found.
+   * Returns the first issue in the list.
+   * @throws IllegalStateException if the list is empty.
    */
   Issue first();
 
+  /**
+   * Returns the rule associated to the given issue.
+   */
   Rule rule(Issue issue);
 
   /**
@@ -62,22 +68,33 @@ public interface IssueQueryResult {
    */
   Collection<Component> projects();
 
-
   @CheckForNull
   ActionPlan actionPlan(Issue issue);
 
+  /**
+   * The action plans involved in the paginated {@link #issues()}.
+   */
   Collection<ActionPlan> actionPlans();
 
   /**
-   * The users involved in the paginated {@link #issues()}, for example people who added a comment, created an issue
+   * The users involved in the paginated {@link #issues()}, for example people who added a comment, reported an issue
    * or are assigned to issues.
    */
   Collection<User> users();
 
+  /**
+   * Returns the user with the given login. Users that are not returned by {@link #users()} are ignored.
+   */
   @CheckForNull
   User user(String login);
 
+  /**
+   * Non-null data about paging of issues
+   */
   Paging paging();
 
+  /**
+   * True if too many issues have been found. In this case results are truncated.
+   */
   boolean maxResultsReached();
 }
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/issue/RubyIssueService.java b/sonar-plugin-api/src/main/java/org/sonar/api/issue/RubyIssueService.java
index 7956b5e17f0..440105e5787 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/issue/RubyIssueService.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/issue/RubyIssueService.java
@@ -36,17 +36,17 @@ public interface RubyIssueService extends ServerComponent {
   /**
    * Search for an issue by its key.
    * <p/>
-   * Ruby example: {@code Api.issues.find('ABCDE-12345')}
+   * Ruby example: <code>result = Api.issues.find('ABCDE-12345')</code>
    */
   IssueQueryResult find(String issueKey);
 
   /**
    * Search for issues.
    * <p/>
-   * Ruby example: {@code Api.issues.find({'statuses' => ['OPEN', 'RESOLVED'], 'assignees' => 'john,carla')}.
+   * Ruby example: <code>Api.issues.find({'statuses' => ['OPEN', 'RESOLVED'], 'assignees' => 'john,carla')}</code>
    * <p/>
-   * <b>Keys of parameters must be Ruby strings but not symbols</b>. Multi-value parameters can be arrays ({@code ['OPEN', 'RESOLVED']}) or
-   * comma-separated list of strings ({@code 'OPEN,RESOLVED'}).
+   * <b>Keys of parameters must be Ruby strings but not symbols</b>. Multi-value parameters can be arrays (<code>['OPEN', 'RESOLVED']</code>) or
+   * comma-separated list of strings (<code>'OPEN,RESOLVED'</code>).
    * <p/>
    * Optional parameters are:
    * <ul>
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/issue/action/Action.java b/sonar-plugin-api/src/main/java/org/sonar/api/issue/action/Action.java
index a797d20106c..3f1c50fc3b0 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/issue/action/Action.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/issue/action/Action.java
@@ -29,18 +29,20 @@ import java.util.List;
 
 import static com.google.common.collect.Lists.newArrayList;
 
+/**
+ * @since 3.6
+ */
 public class Action {
 
   private final String key;
   private final List<Condition> conditions;
   private final List<Function> functions;
 
-  public Action(String key) {
+  Action(String key) {
+    Preconditions.checkArgument(!Strings.isNullOrEmpty(key), "Action key must be set");
     this.key = key;
     this.conditions = newArrayList();
     this.functions = newArrayList();
-
-    Preconditions.checkArgument(!Strings.isNullOrEmpty(key), "Action key must be set");
   }
 
   public String key() {
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/issue/action/Actions.java b/sonar-plugin-api/src/main/java/org/sonar/api/issue/action/Actions.java
index ae6ccb0e2cb..58522414816 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/issue/action/Actions.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/issue/action/Actions.java
@@ -25,6 +25,9 @@ import java.util.List;
 
 import static com.google.common.collect.Lists.newArrayList;
 
+/**
+ * @since 3.6
+ */
 public class Actions implements ServerExtension {
 
   private final List<Action> actions;
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/issue/condition/HasIssuePropertyCondition.java b/sonar-plugin-api/src/main/java/org/sonar/api/issue/condition/HasIssuePropertyCondition.java
index d6386e9ed8b..cb99f21d8e3 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/issue/condition/HasIssuePropertyCondition.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/issue/condition/HasIssuePropertyCondition.java
@@ -19,15 +19,13 @@
  */
 package org.sonar.api.issue.condition;
 
-import com.google.common.annotations.Beta;
 import com.google.common.base.Preconditions;
 import com.google.common.base.Strings;
 import org.sonar.api.issue.Issue;
 
 /**
- * @since 3.1
+ * @since 3.6
  */
-@Beta
 public final class HasIssuePropertyCondition implements Condition {
 
   private final String propertyKey;
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/issue/internal/DefaultIssue.java b/sonar-plugin-api/src/main/java/org/sonar/api/issue/internal/DefaultIssue.java
index 5ba60e544d1..0a4ba0394e8 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/issue/internal/DefaultIssue.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/issue/internal/DefaultIssue.java
@@ -22,6 +22,7 @@ package org.sonar.api.issue.internal;
 import com.google.common.base.Objects;
 import com.google.common.base.Preconditions;
 import com.google.common.base.Strings;
+import com.google.common.collect.ImmutableList;
 import com.google.common.collect.ImmutableMap;
 import com.google.common.collect.Lists;
 import com.google.common.collect.Maps;
@@ -35,7 +36,6 @@ import org.sonar.api.rule.Severity;
 
 import javax.annotation.CheckForNull;
 import javax.annotation.Nullable;
-
 import java.io.Serializable;
 import java.util.Collections;
 import java.util.Date;
@@ -43,6 +43,8 @@ import java.util.List;
 import java.util.Map;
 
 /**
+ * PLUGINS MUST NOT BE USED THIS CLASS, EXCEPT FOR UNIT TESTING.
+ *
  * @since 3.6
  */
 public class DefaultIssue implements Issue {
@@ -275,9 +277,9 @@ public class DefaultIssue implements Issue {
   /**
    * True when one of the following conditions is true :
    * <ul>
-   *   <li>the related component has been deleted or renamed</li>
-   *   <li>the rule has been deleted (eg. on plugin uninstall)</li>
-   *   <li>the rule has been disabled in the Quality profile</li>
+   * <li>the related component has been deleted or renamed</li>
+   * <li>the rule has been deleted (eg. on plugin uninstall)</li>
+   * <li>the rule has been disabled in the Quality profile</li>
    * </ul>
    */
   public boolean isEndOfLife() {
@@ -384,7 +386,10 @@ public class DefaultIssue implements Issue {
 
   @SuppressWarnings("unchcked")
   public List<IssueComment> comments() {
-    return Objects.firstNonNull(comments, Collections.<IssueComment>emptyList());
+    if (comments == null) {
+      return Collections.emptyList();
+    }
+    return ImmutableList.copyOf(comments);
   }
 
   @CheckForNull
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/issue/internal/DefaultIssueComment.java b/sonar-plugin-api/src/main/java/org/sonar/api/issue/internal/DefaultIssueComment.java
index 318b6c7117e..2418943cc3d 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/issue/internal/DefaultIssueComment.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/issue/internal/DefaultIssueComment.java
@@ -29,6 +29,8 @@ import java.util.Date;
 import java.util.UUID;
 
 /**
+ * PLUGINS MUST NOT BE USED THIS CLASS, EXCEPT FOR UNIT TESTING.
+ *
  * @since 3.6
  */
 public class DefaultIssueComment implements Serializable, IssueComment {
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/issue/internal/FieldDiffs.java b/sonar-plugin-api/src/main/java/org/sonar/api/issue/internal/FieldDiffs.java
index b0d44ee6bf9..9d954cbd77a 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/issue/internal/FieldDiffs.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/issue/internal/FieldDiffs.java
@@ -30,6 +30,8 @@ import java.util.Date;
 import java.util.Map;
 
 /**
+ * PLUGINS MUST NOT BE USED THIS CLASS, EXCEPT FOR UNIT TESTING.
+ *
  * @since 3.6
  */
 public class FieldDiffs implements Serializable {
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/issue/internal/IssueChangeContext.java b/sonar-plugin-api/src/main/java/org/sonar/api/issue/internal/IssueChangeContext.java
index 1e462235a96..e8a0b6cef3a 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/issue/internal/IssueChangeContext.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/issue/internal/IssueChangeContext.java
@@ -26,13 +26,15 @@ import java.io.Serializable;
 import java.util.Date;
 
 /**
+ * PLUGINS MUST NOT BE USED THIS CLASS, EXCEPT FOR UNIT TESTING.
+ *
  * @since 3.6
  */
 public class IssueChangeContext implements Serializable {
 
-  private String login;
-  private Date date;
-  private boolean scan;
+  private final String login;
+  private final Date date;
+  private final boolean scan;
 
   private IssueChangeContext(@Nullable String login, Date date, boolean scan) {
     this.login = login;
diff --git a/sonar-plugin-api/src/test/java/org/sonar/api/issue/internal/DefaultIssueTest.java b/sonar-plugin-api/src/test/java/org/sonar/api/issue/internal/DefaultIssueTest.java
index 247e60d41d2..b50e7f32594 100644
--- a/sonar-plugin-api/src/test/java/org/sonar/api/issue/internal/DefaultIssueTest.java
+++ b/sonar-plugin-api/src/test/java/org/sonar/api/issue/internal/DefaultIssueTest.java
@@ -22,6 +22,9 @@ package org.sonar.api.issue.internal;
 import com.google.common.collect.ImmutableMap;
 import org.apache.commons.lang.StringUtils;
 import org.junit.Test;
+import org.sonar.api.issue.IssueComment;
+
+import java.util.List;
 
 import static org.fest.assertions.Assertions.assertThat;
 import static org.fest.assertions.Fail.fail;
@@ -112,4 +115,21 @@ public class DefaultIssueTest {
     assertThat(a1).isNotEqualTo(b);
     assertThat(a1.hashCode()).isEqualTo(a1.hashCode());
   }
+
+  @Test
+  public void comments_should_not_be_modifiable() throws Exception {
+    DefaultIssue issue = new DefaultIssue().setKey("AAA");
+
+    List<IssueComment> comments = issue.comments();
+    assertThat(comments).isEmpty();
+
+    try {
+      comments.add(new DefaultIssueComment());
+      fail();
+    } catch (UnsupportedOperationException e) {
+      // ok
+    } catch (Exception e) {
+      fail("Unexpected exception: " + e);
+    }
+  }
 }