From fda70394aef38d9e6003521acc516fce3fcb29a4 Mon Sep 17 00:00:00 2001
From: Simon Brandhof <simon.brandhof@gmail.com>
Date: Wed, 5 Jun 2013 17:11:36 +0200
Subject: [PATCH] SONAR-3755 add javadoc to issue API

---
 .../java/org/sonar/api/issue/IssueFinder.java     |  2 +-
 .../java/org/sonar/api/issue/NoSonarFilter.java   |  6 ++++++
 .../org/sonar/api/issue/RubyIssueService.java     | 15 ++++++++++++---
 .../src/main/java/org/sonar/api/rule/RuleKey.java |  1 +
 .../main/java/org/sonar/api/rule/Severity.java    |  5 ++++-
 5 files changed, 24 insertions(+), 5 deletions(-)

diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/issue/IssueFinder.java b/sonar-plugin-api/src/main/java/org/sonar/api/issue/IssueFinder.java
index 85241153f7d..bb80ff25ccc 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/issue/IssueFinder.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/issue/IssueFinder.java
@@ -22,7 +22,7 @@ package org.sonar.api.issue;
 import org.sonar.api.ServerComponent;
 
 /**
- * Search for issues. This component can be used only by server-side extensions. Batch extensions should
+ * Search for issues. This IoC component can be used only by server-side extensions. {@link org.sonar.api.BatchExtension}s should
  * use the perspective {@link Issuable}.
  *
  * @since 3.6
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/issue/NoSonarFilter.java b/sonar-plugin-api/src/main/java/org/sonar/api/issue/NoSonarFilter.java
index 939ef869a51..88c6724b720 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/issue/NoSonarFilter.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/issue/NoSonarFilter.java
@@ -26,6 +26,12 @@ import java.util.Map;
 import java.util.Set;
 
 /**
+ * Issue filter used to ignore issues created on lines commented with the tag "NOSONAR".
+ * <p/>
+ * Plugins, via {@link org.sonar.api.BatchExtension}s, must feed this filter by registering the
+ * lines that contain "NOSONAR". Note that filters are disabled for the issues reported by
+ * end-users from UI or web services.
+ *
  * @since 3.6
  */
 public class NoSonarFilter implements IssueFilter {
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 4da22172578..7956b5e17f0 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
@@ -33,13 +33,22 @@ import java.util.Map;
  */
 public interface RubyIssueService extends ServerComponent {
 
+  /**
+   * Search for an issue by its key.
+   * <p/>
+   * Ruby example: {@code Api.issues.find('ABCDE-12345')}
+   */
   IssueQueryResult find(String issueKey);
 
   /**
    * Search for issues.
    * <p/>
-   * Ruby: <code>Api.issues.find(hash_of_parameters)</code>. <b></B>Keys of parameters must be Ruby strings but not symbols</b>.
+   * Ruby example: {@code Api.issues.find({'statuses' => ['OPEN', 'RESOLVED'], 'assignees' => 'john,carla')}.
+   * <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'}).
    * <p/>
+   * Optional parameters are:
    * <ul>
    *   <li>'issues': list of issue keys</li>
    *   <li>'severities': list of severity to match. See constants in {@link org.sonar.api.rule.Severity}</li>
@@ -61,8 +70,8 @@ public interface RubyIssueService extends ServerComponent {
    *   <li>'pageSize': maximum number of results per page. Default is {@link org.sonar.api.issue.IssueQuery#DEFAULT_PAGE_SIZE},
    *   except when the parameter 'components' is set. In this case there's no limit by default (all results in the same page).</li>
    *   <li>'pageIndex': index of the selected page. Default is 1.</li>
-   *   <li>'sort': TODO</li>
-   *   <li>'asc': TODO </li>
+   *   <li>'sort': field to sort on. See supported values in {@link IssueQuery}</li>
+   *   <li>'asc': ascending or descending sort? Value can be a boolean or strings 'true'/'false'</li>
    * </ul>
    */
   IssueQueryResult find(Map<String, Object> parameters);
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/rule/RuleKey.java b/sonar-plugin-api/src/main/java/org/sonar/api/rule/RuleKey.java
index 40614340393..4594f30a086 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/rule/RuleKey.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/rule/RuleKey.java
@@ -26,6 +26,7 @@ import java.io.Serializable;
 
 /**
  * Key of a rule. Unique among all the rule repositories.
+ *
  * @since 3.6
  */
 public class RuleKey implements Serializable {
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/rule/Severity.java b/sonar-plugin-api/src/main/java/org/sonar/api/rule/Severity.java
index 64fa90c2825..344d0961be8 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/rule/Severity.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/rule/Severity.java
@@ -23,6 +23,9 @@ import com.google.common.collect.ImmutableList;
 
 import java.util.List;
 
+/**
+ * @since 3.6
+ */
 public final class Severity {
 
   private Severity() {
@@ -36,7 +39,7 @@ public final class Severity {
   public static final String BLOCKER = "BLOCKER";
 
   /**
-   * All the supported severities, orderest from {@link #INFO} to {@link #BLOCKER}.
+   * All the supported severity values, ordered from {@link #INFO} to {@link #BLOCKER}.
    */
   public static final List<String> ALL = ImmutableList.of(INFO, MINOR, MAJOR, CRITICAL, BLOCKER);
 }
-- 
2.39.5