Add some javadoc to org.sonar.api.conf.PropertyDef

2 files changed, 19 insertions, 0 deletions

diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/Property.java b/sonar-plugin-api/src/main/java/org/sonar/api/Property.java
index 7638149e477..fd8d93edd58 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/Property.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/Property.java
@@ -38,6 +38,8 @@ import java.lang.annotation.Target;
  * (see method <code>getConfiguration()</code>).
  * <p/>
  * <p><strong>Must be used in <code>org.sonar.api.Plugin</code> classes only.</strong></p>
+ * <p></p>
+ * It's recommended to use the class {@link org.sonar.api.config.PropertyDef} since v3.6.
  *
  * @since 1.10
  */
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/config/PropertyDef.java b/sonar-plugin-api/src/main/java/org/sonar/api/config/PropertyDef.java
index 80bac83f5d0..7260bf3952f 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/config/PropertyDef.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/config/PropertyDef.java
@@ -38,6 +38,23 @@ import java.util.List;
 import static com.google.common.collect.Lists.newArrayList;
 
 /**
+ * Declare a plugin property. Values are available at runtime through the component {@link Settings}.
+ * <p></p>
+ * It's the programmatic alternative to the annotation {@link org.sonar.api.Property}. It is more
+ * testable and adds new features like sub-categories and ordering.
+ * <p/>
+ * Example:
+ * <pre>
+ *   public class MyPlugin extends SonarPlugin {
+ *     public List getExtensions() {
+ *       return Arrays.asList(
+ *         PropertyDef.builder("sonar.foo").name("Foo").build(),
+ *         PropertyDef.builder("sonar.bar").name("Bar").type(PropertyType.INTEGER).build()
+ *       );
+ *     }
+ *   }
+ * </pre>
+ *
  * @since 3.6
  */
 public final class PropertyDef implements BatchExtension, ServerExtension {