From 78c1f8b5d87cfe476c83398bfd324da35a45bc93 Mon Sep 17 00:00:00 2001
From: Simon Brandhof <simon.brandhof@sonarsource.com>
Date: Tue, 7 Oct 2014 21:43:59 +0200
Subject: [PATCH] Fix some javadocs

---
 .../src/main/java/org/sonar/api/batch/rule/Checks.java |  7 +++----
 .../src/main/java/org/sonar/api/batch/rule/Rules.java  | 10 ++++++++++
 .../java/org/sonar/api/database/DatabaseSession.java   |  2 +-
 .../org/sonar/api/scan/filesystem/package-info.java    |  3 +++
 .../org/sonar/api/server/rule/RulesDefinition.java     |  2 +-
 .../server/rule/RulesDefinitionAnnotationLoader.java   |  1 +
 .../api/server/rule/RulesDefinitionXmlLoader.java      |  1 +
 7 files changed, 20 insertions(+), 6 deletions(-)

diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/rule/Checks.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/rule/Checks.java
index ea8d36749eb..ab8ff4fbdec 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/rule/Checks.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/rule/Checks.java
@@ -41,9 +41,9 @@ import java.util.Map;
  * <p/>
  * Example of check class:
  * <pre>
- *   @Rule(key = "S001")
+ *   {@literal @}org.sonar.check.Rule(key = "S001")
  *   public class CheckS001 {
- *     @RuleProperty
+ *     {@literal @}org.sonar.check.RuleProperty
  *     private String pattern;
  *
  *     public String getPattern() {
@@ -69,8 +69,7 @@ import java.util.Map;
  *
  *       // Checks are used to detect issues on source code
  *
- *       // checks.ruleKey(obj) can be used to create the detected
- *       // issues.
+ *       // checks.ruleKey(obj) can be used to create the related issues
  *     }
  *   }
  * </pre>
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/rule/Rules.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/rule/Rules.java
index 22521ce0115..83d9cc64faa 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/rule/Rules.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/rule/Rules.java
@@ -26,15 +26,25 @@ import javax.annotation.CheckForNull;
 import java.util.Collection;
 
 /**
+ * Searches for rules. This component is available by dependency injection. It must not
+ * be extended by plugins.
+ *
  * @since 4.2
  */
 public interface Rules {
 
+  /**
+   * Get a rule by its key. Returns <code>null</code> if rule does not exist.
+   */
   @CheckForNull
   Rule find(RuleKey key);
 
   Collection<Rule> findAll();
 
+  /**
+   * Get the rules of the given repository. Returns an empty collection if the
+   * repository does not exist.
+   */
   Collection<Rule> findByRepository(String repository);
 
 }
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/database/DatabaseSession.java b/sonar-plugin-api/src/main/java/org/sonar/api/database/DatabaseSession.java
index b9c12ac320e..74bd4939f42 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/database/DatabaseSession.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/database/DatabaseSession.java
@@ -26,7 +26,7 @@ import javax.persistence.Query;
 import java.util.List;
 
 /**
- * This component should not accessible from plugin API
+ * This component should not be accessed by plugins. Database is not an API.
  *
  * @since 1.10
  */
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/scan/filesystem/package-info.java b/sonar-plugin-api/src/main/java/org/sonar/api/scan/filesystem/package-info.java
index b28c437c37f..e4820ed925b 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/scan/filesystem/package-info.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/scan/filesystem/package-info.java
@@ -17,6 +17,9 @@
  * along with this program; if not, write to the Free Software Foundation,
  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  */
+/**
+ * Replaced by {@link org.sonar.api.batch.fs}
+ */
 @ParametersAreNonnullByDefault
 package org.sonar.api.scan.filesystem;
 
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/server/rule/RulesDefinition.java b/sonar-plugin-api/src/main/java/org/sonar/api/server/rule/RulesDefinition.java
index aae2be99ea3..ac9e7c34fa3 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/server/rule/RulesDefinition.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/server/rule/RulesDefinition.java
@@ -41,7 +41,7 @@ import java.util.Map;
 import java.util.Set;
 
 /**
- * Defines the coding rules. For example the Java Findbugs plugin provides an implementation of
+ * Defines some coding rules of the same repository. For example the Java Findbugs plugin provides an implementation of
  * this extension point in order to define the rules that it supports.
  * <p/>
  * This interface replaces the deprecated class org.sonar.api.rules.RuleRepository.
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/server/rule/RulesDefinitionAnnotationLoader.java b/sonar-plugin-api/src/main/java/org/sonar/api/server/rule/RulesDefinitionAnnotationLoader.java
index 5c455ebdbf6..0c2a08f3dcc 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/server/rule/RulesDefinitionAnnotationLoader.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/server/rule/RulesDefinitionAnnotationLoader.java
@@ -39,6 +39,7 @@ import java.util.List;
  * Read definitions of rules based on the annotations provided by sonar-check-api. It is used
  * to feed {@link RulesDefinition}.
  *
+ * @see org.sonar.api.server.rule.RulesDefinition
  * @since 4.3
  */
 public class RulesDefinitionAnnotationLoader {
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/server/rule/RulesDefinitionXmlLoader.java b/sonar-plugin-api/src/main/java/org/sonar/api/server/rule/RulesDefinitionXmlLoader.java
index 240420d1ee2..72e2b545f06 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/server/rule/RulesDefinitionXmlLoader.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/server/rule/RulesDefinitionXmlLoader.java
@@ -77,6 +77,7 @@ import java.util.List;
  * &lt;/rules&gt;
  * </pre>
  *
+ * @see org.sonar.api.server.rule.RulesDefinition
  * @since 4.3
  */
 public class RulesDefinitionXmlLoader implements ServerComponent {
-- 
2.39.5