Added javadoc to maven-yang-plugin. 93/193/1
authorMaros Marsalek <mmarsale@cisco.com>
Mon, 15 Apr 2013 12:12:42 +0000 (14:12 +0200)
committerMaros Marsalek <mmarsale@cisco.com>
Mon, 15 Apr 2013 12:23:39 +0000 (14:23 +0200)
Documentation can be generated using mvn site command.
Useful information about goals and cofiguration is located under
Project Reports / Plugin Documentation in generated docs.

Signed-off-by: Maros Marsalek <mmarsale@cisco.com>
opendaylight/sal/yang-prototype/code-generator/maven-yang-plugin/pom.xml
opendaylight/sal/yang-prototype/code-generator/maven-yang-plugin/src/main/java/org/opendaylight/controller/yang2sources/plugin/ConfigArg.java
opendaylight/sal/yang-prototype/code-generator/maven-yang-plugin/src/main/java/org/opendaylight/controller/yang2sources/plugin/YangToResourcesMojo.java
opendaylight/sal/yang-prototype/code-generator/maven-yang-plugin/src/main/java/org/opendaylight/controller/yang2sources/plugin/YangToSourcesMojo.java
opendaylight/sal/yang-prototype/code-generator/maven-yang/src/main/java/org/opendaylight/controller/yang2sources/spi/CodeGenerator.java
opendaylight/sal/yang-prototype/code-generator/maven-yang/src/main/java/org/opendaylight/controller/yang2sources/spi/ResourceGenerator.java

index 1dd5691..f9e3a9a 100644 (file)
@@ -9,6 +9,14 @@
 
     <artifactId>maven-yang-plugin</artifactId>
     <packaging>maven-plugin</packaging>
+    <description>
+        This plugin is a wrapper for "yang to source code" generation.
+        It can be configured by a set of third-party code generators and resource providers.
+        For further info see available goals.
+        Sample usage:
+
+        TODO: add sample usage when finished
+    </description>
 
     <dependencies>
         <dependency>
         </dependency>
     </dependencies>
 
+    <reporting>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-plugin-plugin</artifactId>
+                <version>3.2</version>
+            </plugin>
+        </plugins>
+    </reporting>
+
     <build>
         <plugins>
             <plugin>
index f6602e6..85f2d89 100644 (file)
@@ -12,7 +12,7 @@ import java.io.File;
 import com.google.common.base.Preconditions;
 
 /**
- * Complex configuration arguments
+ * Base complex configuration arguments
  */
 public abstract class ConfigArg {
 
@@ -31,6 +31,9 @@ public abstract class ConfigArg {
 
     public abstract void check();
 
+    /**
+     * Configuration argument for resource generator class and output directory.
+     */
     public static final class ResourceProviderArg extends ConfigArg {
         private String resourceProviderClass;
 
@@ -59,7 +62,7 @@ public abstract class ConfigArg {
     }
 
     /**
-     * Transfer object for code generator class and output directory.
+     * Configuration argument for code generator class and output directory.
      */
     public static final class CodeGeneratorArg extends ConfigArg {
         private String codeGeneratorClass;
index 7bb49dc..b449049 100644 (file)
@@ -23,14 +23,40 @@ import org.opendaylight.controller.yang2sources.spi.ResourceGenerator;
 import com.google.common.annotations.VisibleForTesting;
 import com.google.common.collect.Maps;
 
+/**
+ * Generate resources from yang files using user provided set of
+ * {@link ResourceGenerator}s. Can be used to copy yang files that served as
+ * blueprint for code generation into resources directory. Steps of this
+ * process:
+ * <ol>
+ * <li>List yang files from {@link #yangFilesRootDir} (If this goal is in the
+ * same execution as generate-sources, the same cached list will be used and the
+ * root folder will not be searched for yang files twice)</li>
+ * <li>For each {@link ResourceGenerator} from {@link #resourceProviders}:</li>
+ * <ol>
+ * <li>Instantiate using default constructor</li>
+ * <li>Call {@link ResourceGenerator#generateResourceFiles(Collection, File)}</li>
+ * </ol>
+ * </ol>
+ */
 @Mojo(name = "generate-resources", defaultPhase = LifecyclePhase.GENERATE_RESOURCES)
 public final class YangToResourcesMojo extends AbstractMojo {
 
     private static final String LOG_PREFIX = "yang-to-resources:";
 
+    /**
+     * Classes implementing {@link ResourceGenerator} interface. An instance
+     * will be created out of every class using default constructor. Method
+     * {@link ResourceGenerator#generateResourceFiles(Collection, File)} will be
+     * called on every instance.
+     */
     @Parameter(required = true)
     private ResourceProviderArg[] resourceProviders;
 
+    /**
+     * Source directory that will be recursively searched for yang files (ending
+     * with .yang suffix).
+     */
     @Parameter(required = true)
     private String yangFilesRootDir;
 
index 2928298..32ad2ab 100644 (file)
@@ -29,14 +29,37 @@ import org.opendaylight.controller.yang2sources.spi.CodeGenerator;
 import com.google.common.annotations.VisibleForTesting;
 import com.google.common.collect.Maps;
 
+/**
+ * Generate sources from yang files using user provided set of
+ * {@link CodeGenerator}s. Steps of this process:
+ * <ol>
+ * <li>List yang files from {@link #yangFilesRootDir}</li>
+ * <li>Process yang files using {@link YangModelParserImpl}</li>
+ * <li>For each {@link CodeGenerator} from {@link #codeGenerators}:</li>
+ * <ol>
+ * <li>Instantiate using default constructor</li>
+ * <li>Call {@link CodeGenerator#generateSources(SchemaContext, File)}</li>
+ * </ol>
+ * </ol>
+ */
 @Mojo(name = "generate-sources", defaultPhase = LifecyclePhase.GENERATE_SOURCES)
 public final class YangToSourcesMojo extends AbstractMojo {
 
     private static final String LOG_PREFIX = "yang-to-sources:";
 
+    /**
+     * Classes implementing {@link CodeGenerator} interface. An instance will be
+     * created out of every class using default constructor. Method
+     * {@link CodeGenerator#generateSources(SchemaContext, File)} will be called
+     * on every instance.
+     */
     @Parameter(required = true)
     private CodeGeneratorArg[] codeGenerators;
 
+    /**
+     * Source directory that will be recursively searched for yang files (ending
+     * with .yang suffix).
+     */
     @Parameter(required = true)
     private String yangFilesRootDir;
 
index 2b39320..534c37d 100644 (file)
@@ -12,7 +12,21 @@ import java.util.Collection;
 
 import org.opendaylight.controller.yang.model.api.SchemaContext;
 
+/**
+ * Classes implementing this interface can be submitted to maven-yang-plugin's
+ * generate-sources goal.
+ */
 public interface CodeGenerator {
 
+    /**
+     * Generate sources from provided {@link SchemaContext}
+     * 
+     * @param context
+     *            parsed from yang files
+     * @param outputBaseDir
+     *            expected output directory for generated sources configured by
+     *            user
+     * @return collection of files that were generated from schema context
+     */
     Collection<File> generateSources(SchemaContext context, File outputBaseDir);
 }
index 9095155..2638dc3 100644 (file)
@@ -10,7 +10,20 @@ package org.opendaylight.controller.yang2sources.spi;
 import java.io.File;
 import java.util.Collection;
 
+/**
+ * Classes implementing this interface can be submitted to maven-yang-plugin's
+ * generate-resources goal.
+ */
 public interface ResourceGenerator {
 
+    /**
+     * Generate resources (e.g. copy files into resources folder) from provided
+     * list of yang files
+     * 
+     * @param resources
+     *            list of parsed yang files
+     * @param outputBaseDir
+     *            expected output directory for resources configured by user
+     */
     void generateResourceFiles(Collection<File> resources, File outputBaseDir);
 }