SONAR-5931 Update documentation

18 files changed, 74 insertions, 65 deletions

diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/SensorContext.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/SensorContext.java
index 6a5463e67f9..77da586cc5a 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/SensorContext.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/SensorContext.java
@@ -105,12 +105,12 @@ public interface SensorContext extends org.sonar.api.batch.sensor.SensorContext
   // ----------- MEASURES ON PROJECT --------------
 
   /**
-   * Find a project measure
+   * @deprecated since 5.1 Sensors should not read but only save data
    */
   <G extends Serializable> Measure<G> getMeasure(Metric<G> metric);
 
   /**
-   * All measures of the project. Never return null.
+   * @deprecated since 5.1 Sensors should not read but only save data
    */
   <M> M getMeasures(MeasuresFilter<M> filter);
 
@@ -127,7 +127,7 @@ public interface SensorContext extends org.sonar.api.batch.sensor.SensorContext
   // ----------- MEASURES ON RESOURCES --------------
 
   /**
-   * Find a measure for this project
+   * @deprecated since 5.1 Sensors should not read but only save data
    */
   <G extends Serializable> Measure<G> getMeasure(Resource resource, Metric<G> metric);
 
@@ -141,7 +141,7 @@ public interface SensorContext extends org.sonar.api.batch.sensor.SensorContext
   String saveResource(Resource resource);
 
   /**
-   * Find all measures for this project. Never return null.
+   * @deprecated since 5.1 Sensors should not read but only save data
    */
   <M> M getMeasures(Resource resource, MeasuresFilter<M> filter);
 
@@ -191,9 +191,6 @@ public interface SensorContext extends org.sonar.api.batch.sensor.SensorContext
 
   // ----------- DEPENDENCIES BETWEEN RESOURCES --------------
 
-  /**
-   * @deprecated since 5.1 use {@link #newDependency()}
-   */
   Dependency saveDependency(Dependency dependency);
 
   /**
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/Sensor.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/Sensor.java
index 01f0e109e53..fe2d78b5cad 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/Sensor.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/Sensor.java
@@ -19,6 +19,7 @@
  */
 package org.sonar.api.batch.sensor;
 
+import com.google.common.annotations.Beta;
 import org.sonar.api.BatchExtension;
 
 /**
@@ -33,6 +34,7 @@ import org.sonar.api.BatchExtension;
  *
  * @since 5.1
  */
+@Beta
 public interface Sensor extends BatchExtension {
 
   /**
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/SensorContext.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/SensorContext.java
index 91c039763fc..b52cb989e4c 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/SensorContext.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/SensorContext.java
@@ -19,6 +19,7 @@
  */
 package org.sonar.api.batch.sensor;
 
+import com.google.common.annotations.Beta;
 import org.sonar.api.batch.AnalysisMode;
 import org.sonar.api.batch.CpdMapping;
 import org.sonar.api.batch.fs.FileSystem;
@@ -26,6 +27,7 @@ import org.sonar.api.batch.rule.ActiveRules;
 import org.sonar.api.batch.sensor.dependency.NewDependency;
 import org.sonar.api.batch.sensor.duplication.NewDuplication;
 import org.sonar.api.batch.sensor.highlighting.NewHighlighting;
+import org.sonar.api.batch.sensor.internal.SensorContextTester;
 import org.sonar.api.batch.sensor.issue.Issue;
 import org.sonar.api.batch.sensor.issue.NewIssue;
 import org.sonar.api.batch.sensor.measure.Measure;
@@ -36,8 +38,10 @@ import java.io.Serializable;
 
 /**
  * See {@link Sensor#execute(SensorContext)}
+ * In order to write unit tests you can use {@link SensorContextTester}
  * @since 5.1
  */
+@Beta
 public interface SensorContext {
 
   /**
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/SensorDescriptor.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/SensorDescriptor.java
index a247e392870..290815df803 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/SensorDescriptor.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/SensorDescriptor.java
@@ -19,6 +19,7 @@
  */
 package org.sonar.api.batch.sensor;
 
+import com.google.common.annotations.Beta;
 import org.sonar.api.batch.fs.InputFile;
 
 /**
@@ -27,6 +28,7 @@ import org.sonar.api.batch.fs.InputFile;
  * See {@link Sensor#describe(SensorDescriptor)}
  * @since 5.1
  */
+@Beta
 public interface SensorDescriptor {
 
   /**
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/dependency/Dependency.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/dependency/Dependency.java
index 56185acaf3a..69644789673 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/dependency/Dependency.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/dependency/Dependency.java
@@ -19,10 +19,12 @@
  */
 package org.sonar.api.batch.sensor.dependency;
 
+import com.google.common.annotations.Beta;
 
 /**
  * @since 5.1
  */
+@Beta
 public interface Dependency {
 
   String fromKey();
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/dependency/NewDependency.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/dependency/NewDependency.java
index 8d62a2f6516..9e0de3c991b 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/dependency/NewDependency.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/dependency/NewDependency.java
@@ -19,6 +19,7 @@
  */
 package org.sonar.api.batch.sensor.dependency;
 
+import com.google.common.annotations.Beta;
 import org.sonar.api.batch.fs.InputFile;
 
 /**
@@ -26,6 +27,7 @@ import org.sonar.api.batch.fs.InputFile;
  * Should not be implemented by client.
  * @since 5.1
  */
+@Beta
 public interface NewDependency {
 
   NewDependency from(InputFile from);
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/duplication/Duplication.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/duplication/Duplication.java
index 7baeef0591c..e449063b7b0 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/duplication/Duplication.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/duplication/Duplication.java
@@ -19,6 +19,7 @@
  */
 package org.sonar.api.batch.sensor.duplication;
 
+import com.google.common.annotations.Beta;
 import org.apache.commons.lang.builder.EqualsBuilder;
 import org.apache.commons.lang.builder.HashCodeBuilder;
 import org.apache.commons.lang.builder.ToStringBuilder;
@@ -35,6 +36,7 @@ import java.util.List;
  * to feed tokens and let the core compute duplications.
  * @since 5.1
  */
+@Beta
 public interface Duplication {
 
   public static class Block {
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/duplication/DuplicationTokenBuilder.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/duplication/DuplicationTokenBuilder.java
deleted file mode 100644
index d43c5d216fd..00000000000
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/duplication/DuplicationTokenBuilder.java
+++ /dev/null
@@ -1,56 +0,0 @@
-/*
- * SonarQube, open source software quality management tool.
- * Copyright (C) 2008-2014 SonarSource
- * mailto:contact AT sonarsource DOT com
- *
- * SonarQube is free software; you can redistribute it and/or
- * modify it under the terms of the GNU Lesser General Public
- * License as published by the Free Software Foundation; either
- * version 3 of the License, or (at your option) any later version.
- *
- * SonarQube is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
- * Lesser General Public License for more details.
- *
- * You should have received a copy of the GNU Lesser General Public License
- * along with this program; if not, write to the Free Software Foundation,
- * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
- */
-package org.sonar.api.batch.sensor.duplication;
-
-
-import com.google.common.annotations.Beta;
-
-/**
- * Experimental, do not use.
- * <p/>
- * This builder is used to define token on files. Tokens are later used to compute duplication.
- * Tokens should be declared in sequential order.
- * Example:
- * <code><pre>
- * DuplicationTokenBuilder tokenBuilder = context.duplicationTokenBuilder(inputFile)
- *  .addToken(1, "public")
- *  .addToken(1, "class")
- *  .addToken(1, "Foo")
- *  .addToken(1, "{")
- *  .addToken(2, "}")
- *  .done();
- * </pre></code>
- * @since 4.5
- */
-@Beta
-public interface DuplicationTokenBuilder {
-
-  /**
-   * Call this method to register a new token.
-   * @param line Line number of the token. Line starts at 1.
-   * @param image Text of the token.
-   */
-  DuplicationTokenBuilder addToken(int line, String image);
-
-  /**
-   * Call this method only once when your are done with defining tokens of the file.
-   */
-  void done();
-}
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/duplication/NewDuplication.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/duplication/NewDuplication.java
index 9cc51c9c7de..d4d06ba600f 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/duplication/NewDuplication.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/duplication/NewDuplication.java
@@ -19,6 +19,7 @@
  */
 package org.sonar.api.batch.sensor.duplication;
 
+import com.google.common.annotations.Beta;
 import org.sonar.api.batch.fs.InputFile;
 
 /**
@@ -34,6 +35,7 @@ import org.sonar.api.batch.fs.InputFile;
  * </pre></code>
  * @since 5.1
  */
+@Beta
 public interface NewDuplication {
 
   /**
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/highlighting/NewHighlighting.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/highlighting/NewHighlighting.java
index 2066ce8ffeb..e391fc6e3f5 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/highlighting/NewHighlighting.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/highlighting/NewHighlighting.java
@@ -19,12 +19,14 @@
  */
 package org.sonar.api.batch.sensor.highlighting;
 
+import com.google.common.annotations.Beta;
 import org.sonar.api.batch.fs.InputFile;
 
 /**
  * This builder is used to define syntax highlighting (aka code coloration) on files.
  * @since 5.1
  */
+@Beta
 public interface NewHighlighting {
 
   /**
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/highlighting/TypeOfText.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/highlighting/TypeOfText.java
index 16064019c91..19f41a5d011 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/highlighting/TypeOfText.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/highlighting/TypeOfText.java
@@ -25,7 +25,7 @@ import com.google.common.annotations.Beta;
  * Experimental, do not use.
  * <p/>
  * Possible types for highlighting code. See sonar-colorizer.css
- * @since 4.5
+ * @since 5.1
  */
 @Beta
 public enum TypeOfText {
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/internal/SensorContextTester.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/internal/SensorContextTester.java
index 1a41ccefe44..2846e0676fb 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/internal/SensorContextTester.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/internal/SensorContextTester.java
@@ -63,7 +63,11 @@ import java.util.List;
 import java.util.Map;
 
 /**
- * Utility class to help testing {@link Sensor}
+ * Utility class to help testing {@link Sensor}.
+ * 
+ * Usage: call {@link #create(File)} to create an "in memory" implementation of {@link SensorContext} then
+ * pass it to your {@link Sensor}. You can then query elements provided by your sensor using methods {@link #allIssues()}, ...
+ * 
  * @since 5.1
  */
 @Beta
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/issue/Issue.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/issue/Issue.java
index d320bd2c11f..e6456ec8803 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/issue/Issue.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/issue/Issue.java
@@ -19,6 +19,7 @@
  */
 package org.sonar.api.batch.sensor.issue;
 
+import com.google.common.annotations.Beta;
 import org.sonar.api.batch.fs.InputPath;
 import org.sonar.api.batch.sensor.Sensor;
 import org.sonar.api.rule.RuleKey;
@@ -30,6 +31,7 @@ import javax.annotation.CheckForNull;
  *
  * @since 5.1
  */
+@Beta
 public interface Issue {
 
   public enum Severity {
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 734627d568d..a98ca7eafd9 100644
--- 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
@@ -19,6 +19,7 @@
  */
 package org.sonar.api.batch.sensor.issue;
 
+import com.google.common.annotations.Beta;
 import org.sonar.api.batch.fs.InputDir;
 import org.sonar.api.batch.fs.InputFile;
 import org.sonar.api.batch.sensor.Sensor;
@@ -32,6 +33,7 @@ import javax.annotation.Nullable;
  *
  * @since 5.1
  */
+@Beta
 public interface NewIssue {
 
   /**
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/measure/Measure.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/measure/Measure.java
index c59f7a7be76..4f82f8587b7 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/measure/Measure.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/measure/Measure.java
@@ -19,6 +19,7 @@
  */
 package org.sonar.api.batch.sensor.measure;
 
+import com.google.common.annotations.Beta;
 import org.sonar.api.batch.fs.InputFile;
 import org.sonar.api.batch.measure.Metric;
 
@@ -31,6 +32,7 @@ import java.io.Serializable;
  * Should not be implemented by client.
  * @since 5.1
  */
+@Beta
 public interface Measure<G extends Serializable> {
 
   /**
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/measure/NewMeasure.java b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/measure/NewMeasure.java
index cf8bccba48b..412e4df9203 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/measure/NewMeasure.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/measure/NewMeasure.java
@@ -19,6 +19,7 @@
  */
 package org.sonar.api.batch.sensor.measure;
 
+import com.google.common.annotations.Beta;
 import org.sonar.api.batch.fs.InputFile;
 import org.sonar.api.batch.measure.Metric;
 
@@ -29,6 +30,7 @@ import java.io.Serializable;
  * Should not be implemented by client.
  * @since 5.1
  */
+@Beta
 public interface NewMeasure<G extends Serializable> {
 
   /**
diff --git a/sonar-plugin-api/src/test/java/org/sonar/api/batch/sensor/highlighting/internal/DefaultHighlightingTest.java b/sonar-plugin-api/src/test/java/org/sonar/api/batch/sensor/highlighting/internal/DefaultHighlightingTest.java
index 2770df6cb31..55900838bc6 100644
--- a/sonar-plugin-api/src/test/java/org/sonar/api/batch/sensor/highlighting/internal/DefaultHighlightingTest.java
+++ b/sonar-plugin-api/src/test/java/org/sonar/api/batch/sensor/highlighting/internal/DefaultHighlightingTest.java
@@ -1,3 +1,22 @@
+/*
+ * SonarQube, open source software quality management tool.
+ * Copyright (C) 2008-2014 SonarSource
+ * mailto:contact AT sonarsource DOT com
+ *
+ * SonarQube is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 3 of the License, or (at your option) any later version.
+ *
+ * SonarQube is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+ */
 package org.sonar.api.batch.sensor.highlighting.internal;
 
 import org.junit.Before;
diff --git a/sonar-plugin-api/src/test/java/org/sonar/api/batch/sensor/internal/SensorContextTesterTest.java b/sonar-plugin-api/src/test/java/org/sonar/api/batch/sensor/internal/SensorContextTesterTest.java
index 090e487ddfe..92a3e262fc1 100644
--- a/sonar-plugin-api/src/test/java/org/sonar/api/batch/sensor/internal/SensorContextTesterTest.java
+++ b/sonar-plugin-api/src/test/java/org/sonar/api/batch/sensor/internal/SensorContextTesterTest.java
@@ -1,3 +1,22 @@
+/*
+ * SonarQube, open source software quality management tool.
+ * Copyright (C) 2008-2014 SonarSource
+ * mailto:contact AT sonarsource DOT com
+ *
+ * SonarQube is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 3 of the License, or (at your option) any later version.
+ *
+ * SonarQube is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+ */
 package org.sonar.api.batch.sensor.internal;
 
 import org.junit.Before;