SONAR-3755 add javadoc to issue API

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 85241153f7d0d4d996a9c8c160aadc6ab59d7bb5..bb80ff25cccbc635c715700020470570458bbbd5 100644 (file)
--- 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 939ef869a51da4c1f779338758e18aa01b28d919..88c6724b720eb4623045dd78d98a8c1f876e4361 100644 (file)
--- 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 4da22172578c1a16a4611f9c065c1573ba7f6615..7956b5e17f0b015877a0212e2a4a2579fcabb8da 100644 (file)
--- 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 406143403936e0ac93cb40ea170c50cb49fc64b0..4594f30a086622b72f9950abbc19ba5c6615025d 100644 (file)
--- 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 64fa90c2825e431ef439f282b53dee4eba5703ea..344d0961be8bb397aef7a43ffaf1278164beb116 100644 (file)
--- 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);
 }