SONAR-1814 add javadoc

diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/ExtensionProvider.java b/sonar-plugin-api/src/main/java/org/sonar/api/ExtensionProvider.java
index 615c57a6631f4d00391df869656d10566ea1f77e..40dcbba5d974029a1cba9bacdfccc9c310e0cba8 100644 (file)
--- a/sonar-plugin-api/src/main/java/org/sonar/api/ExtensionProvider.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/ExtensionProvider.java
@@ -22,6 +22,33 @@ package org.sonar.api;
 import org.picocontainer.injectors.Provider;
 
 /**
+ * Factory of extensions. It allows to dynamically create extensions depending upon runtime context. A use-case is
+ * to create one rule repository by language.
+ *
+ * <p>Constraints are :
+ * <ul>
+ *   <li>the factory is declared in Plugin.getExtensions() as an instance but not as a class</li>
+ *   <li>the factory must have a public method named "provide()"</li>
+ *   <li>the method provide() must return an object or an array of objects. Collections and classes are excluded.</li>
+ *   <li>the methode provide() can accept parameters. These parameters are IoC dependencies.
+ * </ul>
+ * </p>
+ *
+ * <p>Example:
+ * <pre>
+ * public class RuleRepositoryProvider extends ExtensionProvider {
+ *   public RuleRepository[] provide(Language[] languages) {
+ *     RuleRepository[] result = new RuleRepository[languages.length];
+ *     for(int index=0; index &lt; languages.length ; index++) {
+ *       Language language = languages[index];
+ *       result[index] = new RuleRepository(...);
+ *     }
+ *     return result;
+ *   }
+ * }
+ * </pre>
+ * </p>
+ * 
  * @since 2.3
  */
 public abstract class ExtensionProvider implements Extension, Provider {