Add some javadoc

sonar-plugin-api/src/main/java/org/sonar/api/batch/bootstrap/ProjectBuilder.java

@@ -23,7 +23,15 @@ import org.sonar.api.BatchExtension;
 import org.sonar.api.batch.InstantiationStrategy;
 
 /**
- * 
+ * This extension point allows to change project structure at runtime. It is executed once during batch startup.
+ * Some use-cases :
+ * <ul>
+ *   <li>Add sub-projects which are not defined in batch bootstrapper. For example the C# plugin gets the hierarchy
+ *   of sub-projects from the Visual Studio metadata file. The single root pom.xml does not contain any declarations of
+ *   modules</li>
+ *   <li>Change project metadata like description or source directories.</li>
+ * </ul>
+ *
  * @since 2.9
  */
 @InstantiationStrategy(InstantiationStrategy.PER_BATCH)

sonar-plugin-api/src/main/java/org/sonar/api/batch/bootstrap/ProjectDefinition.java

@@ -30,6 +30,9 @@ import java.util.List;
 import java.util.Properties;
 
 /**
+ * Defines project metadata (key, name, source directories, ...). It's generally used by the
+ * {@link org.sonar.api.batch.bootstrap.ProjectBuilder extension point}
+ * 
  * @since 2.9
  */
 public final class ProjectDefinition implements BatchComponent {
@@ -48,9 +51,6 @@ public final class ProjectDefinition implements BatchComponent {
   private List<ProjectDefinition> subProjects = Lists.newArrayList();
   private List<Object> containerExtensions = Lists.newArrayList();
 
-  /**
-   * TODO use factory methods
-   */
   public ProjectDefinition(File baseDir, File workDir, Properties properties) {
     this.baseDir = baseDir;
     this.workDir = workDir;