From b2f8d990393d775068ab5623ee6aca22a6b79d75 Mon Sep 17 00:00:00 2001
From: Simon Brandhof <simon.brandhof@gmail.com>
Date: Thu, 6 Jun 2013 11:05:43 +0200
Subject: [PATCH] Add javadoc to org.sonar.api.config.PropertyDefinition

---
 .../sonar/api/config/PropertyDefinition.java  | 62 ++++++++++++++++---
 .../sonar/api/config/PropertyDefinitions.java |  4 ++
 .../api/issue/internal/package-info.java      |  4 ++
 .../api/config/PropertyDefinitionsTest.java   | 15 +++++
 4 files changed, 78 insertions(+), 7 deletions(-)

diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/config/PropertyDefinition.java b/sonar-plugin-api/src/main/java/org/sonar/api/config/PropertyDefinition.java
index 4cd2a19f6b7..f77e9609a12 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/config/PropertyDefinition.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/config/PropertyDefinition.java
@@ -50,7 +50,7 @@ import static com.google.common.collect.Lists.newArrayList;
  *     public List getExtensions() {
  *       return Arrays.asList(
  *         PropertyDefinition.builder("sonar.foo").name("Foo").build(),
- *         PropertyDefinition.builder("sonar.bar").name("Bar").type(PropertyType.INTEGER).build()
+ *         PropertyDefinition.builder("sonar.bar").name("Bar").defaultValue("123").type(PropertyType.INTEGER).build()
  *       );
  *     }
  *   }
@@ -67,7 +67,7 @@ public final class PropertyDefinition implements BatchExtension, ServerExtension
   private List<String> options;
   private String description;
   /**
-   * @see PropertyDef.Builder#category(String)
+   * @see {@link org.sonar.api.config.PropertyDefinition.Builder#category(String)}
    */
   private String category;
   private List<String> qualifiers;
@@ -77,7 +77,7 @@ public final class PropertyDefinition implements BatchExtension, ServerExtension
   private String deprecatedKey;
   private List<PropertyFieldDefinition> fields;
   /**
-   * @see PropertyDef.Builder#subCategory(String)
+   * @see {@link org.sonar.api.config.PropertyDefinition.Builder#subCategory(String)}
    */
   private String subCategory;
   private int index;
@@ -204,14 +204,14 @@ public final class PropertyDefinition implements BatchExtension, ServerExtension
   }
 
   /**
-   * @see PropertyDef.Builder#category(String)
+   * @see {@link PropertyDefinition.Builder#category(String)}
    */
   public String category() {
     return category;
   }
 
   /**
-   * @see PropertyDef.Builder#subCategory(String)
+   * @see {@link PropertyDefinition.Builder#subCategory(String)}
    */
   public String subCategory() {
     return subCategory;
@@ -284,11 +284,11 @@ public final class PropertyDefinition implements BatchExtension, ServerExtension
     private String description = "";
     private String defaultValue = "";
     /**
-     * @see PropertyDef.Builder#category(String)
+     * @see {@link PropertyDefinition.Builder#category(String)}
      */
     private String category = "";
     /**
-     * @see PropertyDef.Builder#subCategory(String)
+     * @see {@link PropertyDefinition.Builder#subCategory(String)}
      */
     private String subCategory = "";
     private List<String> onQualifiers = newArrayList();
@@ -341,24 +341,64 @@ public final class PropertyDefinition implements BatchExtension, ServerExtension
       return this;
     }
 
+    /**
+     * The property will be available in General Settings AND in the components
+     * with the given qualifiers.
+     * <p/>
+     * For example @{code onQualifiers(Qualifiers.PROJECT)} allows to configure the
+     * property in General Settings and in Project Settings.
+     * <p/>
+     * See supported constant values in {@link Qualifiers}. By default property is available
+     * only in General Settings.
+     */
     public Builder onQualifiers(String first, String... rest) {
       this.onQualifiers.addAll(Lists.asList(first, rest));
       this.global = true;
       return this;
     }
 
+    /**
+     * The property will be available in General Settings AND in the components
+     * with the given qualifiers.
+     * <p/>
+     * For example @{code onQualifiers(Arrays.asList(Qualifiers.PROJECT))} allows to configure the
+     * property in General Settings and in Project Settings.
+     * <p/>
+     * See supported constant values in {@link Qualifiers}. By default property is available
+     * only in General Settings.
+     */
     public Builder onQualifiers(List<String> qualifiers) {
       this.onQualifiers.addAll(ImmutableList.copyOf(qualifiers));
       this.global = true;
       return this;
     }
 
+    /**
+     * The property will be available in the components
+     * with the given qualifiers, but NOT in General Settings.
+     * <p/>
+     * For example @{code onlyOnQualifiers(Qualifiers.PROJECT)} allows to configure the
+     * property in Project Settings only.
+     * <p/>
+     * See supported constant values in {@link Qualifiers}. By default property is available
+     * only in General Settings.
+     */
     public Builder onlyOnQualifiers(String first, String... rest) {
       this.onlyOnQualifiers.addAll(Lists.asList(first, rest));
       this.global = false;
       return this;
     }
 
+    /**
+     * The property will be available in the components
+     * with the given qualifiers, but NOT in General Settings.
+     * <p/>
+     * For example @{code onlyOnQualifiers(Arrays.asList(Qualifiers.PROJECT))} allows to configure the
+     * property in Project Settings only.
+     * <p/>
+     * See supported constant values in {@link Qualifiers}. By default property is available
+     * only in General Settings.
+     */
     public Builder onlyOnQualifiers(List<String> qualifiers) {
       this.onlyOnQualifiers.addAll(ImmutableList.copyOf(qualifiers));
       this.global = false;
@@ -405,11 +445,19 @@ public final class PropertyDefinition implements BatchExtension, ServerExtension
       return this;
     }
 
+    /**
+     * Flag the property as hidden. Hidden properties are not displayed in Settings pages
+     * but allow plugins to benefit from type and default values when calling {@link Settings}.
+     */
     public Builder hidden() {
       this.hidden = true;
       return this;
     }
 
+    /**
+     * Set the order index in Settings pages. A property with a lower index is displayed
+     * before properties with higher index.
+     */
     public Builder index(int index) {
       this.index = index;
       return this;
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/config/PropertyDefinitions.java b/sonar-plugin-api/src/main/java/org/sonar/api/config/PropertyDefinitions.java
index c557a309d89..b729e1064af 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/config/PropertyDefinitions.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/config/PropertyDefinitions.java
@@ -56,6 +56,10 @@ public final class PropertyDefinitions implements BatchComponent, ServerComponen
     }
   }
 
+  public PropertyDefinitions(Collection<PropertyDefinition> components) {
+    addComponents(components);
+  }
+
   public PropertyDefinitions addComponents(Collection components) {
     return addComponents(components, "");
   }
diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/issue/internal/package-info.java b/sonar-plugin-api/src/main/java/org/sonar/api/issue/internal/package-info.java
index 4b2bea8a375..3be812e7dac 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/issue/internal/package-info.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/issue/internal/package-info.java
@@ -17,6 +17,10 @@
  * along with this program; if not, write to the Free Software Foundation,
  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  */
+/**
+ * This package contains classes that MUST NOT be used by plugins,
+ * except for unit testing.
+ */
 @ParametersAreNonnullByDefault
 package org.sonar.api.issue.internal;
 
diff --git a/sonar-plugin-api/src/test/java/org/sonar/api/config/PropertyDefinitionsTest.java b/sonar-plugin-api/src/test/java/org/sonar/api/config/PropertyDefinitionsTest.java
index 4de6c2f4f0c..ed794b4dc8c 100644
--- a/sonar-plugin-api/src/test/java/org/sonar/api/config/PropertyDefinitionsTest.java
+++ b/sonar-plugin-api/src/test/java/org/sonar/api/config/PropertyDefinitionsTest.java
@@ -24,10 +24,25 @@ import org.sonar.api.Properties;
 import org.sonar.api.Property;
 import org.sonar.api.resources.Qualifiers;
 
+import java.util.Arrays;
+import java.util.List;
+
 import static org.fest.assertions.Assertions.assertThat;
 
 public class PropertyDefinitionsTest {
 
+  @Test
+  public void should_build_with_predefined_list_of_definitions() {
+    List<PropertyDefinition> list = Arrays.asList(
+      PropertyDefinition.builder("foo").name("Foo").build(),
+      PropertyDefinition.builder("one").name("One").build(),
+      PropertyDefinition.builder("two").name("Two").defaultValue("2").build()
+    );
+    PropertyDefinitions def = new PropertyDefinitions(list);
+
+    assertProperties(def);
+  }
+
   @Test
   public void should_inspect_plugin_objects() {
     PropertyDefinitions def = new PropertyDefinitions(
-- 
2.39.5