From 570bb0b78439082ca167dcb0a5c9355bafc0b5fd Mon Sep 17 00:00:00 2001 From: Maros Marsalek Date: Mon, 15 Apr 2013 14:12:42 +0200 Subject: [PATCH] Added javadoc to maven-yang-plugin. 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 --- .../code-generator/maven-yang-plugin/pom.xml | 18 +++++++++++++ .../yang2sources/plugin/ConfigArg.java | 7 +++-- .../plugin/YangToResourcesMojo.java | 26 +++++++++++++++++++ .../plugin/YangToSourcesMojo.java | 23 ++++++++++++++++ .../yang2sources/spi/CodeGenerator.java | 14 ++++++++++ .../yang2sources/spi/ResourceGenerator.java | 13 ++++++++++ 6 files changed, 99 insertions(+), 2 deletions(-) diff --git a/opendaylight/sal/yang-prototype/code-generator/maven-yang-plugin/pom.xml b/opendaylight/sal/yang-prototype/code-generator/maven-yang-plugin/pom.xml index 1dd5691411..f9e3a9a6ff 100644 --- a/opendaylight/sal/yang-prototype/code-generator/maven-yang-plugin/pom.xml +++ b/opendaylight/sal/yang-prototype/code-generator/maven-yang-plugin/pom.xml @@ -9,6 +9,14 @@ maven-yang-plugin maven-plugin + + 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 + @@ -55,6 +63,16 @@ + + + + org.apache.maven.plugins + maven-plugin-plugin + 3.2 + + + + diff --git a/opendaylight/sal/yang-prototype/code-generator/maven-yang-plugin/src/main/java/org/opendaylight/controller/yang2sources/plugin/ConfigArg.java b/opendaylight/sal/yang-prototype/code-generator/maven-yang-plugin/src/main/java/org/opendaylight/controller/yang2sources/plugin/ConfigArg.java index f6602e6aae..85f2d8905d 100644 --- a/opendaylight/sal/yang-prototype/code-generator/maven-yang-plugin/src/main/java/org/opendaylight/controller/yang2sources/plugin/ConfigArg.java +++ b/opendaylight/sal/yang-prototype/code-generator/maven-yang-plugin/src/main/java/org/opendaylight/controller/yang2sources/plugin/ConfigArg.java @@ -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; diff --git a/opendaylight/sal/yang-prototype/code-generator/maven-yang-plugin/src/main/java/org/opendaylight/controller/yang2sources/plugin/YangToResourcesMojo.java b/opendaylight/sal/yang-prototype/code-generator/maven-yang-plugin/src/main/java/org/opendaylight/controller/yang2sources/plugin/YangToResourcesMojo.java index 7bb49dc0df..b4490499cf 100644 --- a/opendaylight/sal/yang-prototype/code-generator/maven-yang-plugin/src/main/java/org/opendaylight/controller/yang2sources/plugin/YangToResourcesMojo.java +++ b/opendaylight/sal/yang-prototype/code-generator/maven-yang-plugin/src/main/java/org/opendaylight/controller/yang2sources/plugin/YangToResourcesMojo.java @@ -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: + *
    + *
  1. 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)
    2. + *
  2. For each {@link ResourceGenerator} from {@link #resourceProviders}:
    3. + *
      + *
    1. Instantiate using default constructor
      2. + *
    2. Call {@link ResourceGenerator#generateResourceFiles(Collection, File)}
      3. + *
    + *
+ */ @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; diff --git a/opendaylight/sal/yang-prototype/code-generator/maven-yang-plugin/src/main/java/org/opendaylight/controller/yang2sources/plugin/YangToSourcesMojo.java b/opendaylight/sal/yang-prototype/code-generator/maven-yang-plugin/src/main/java/org/opendaylight/controller/yang2sources/plugin/YangToSourcesMojo.java index 29282988d6..32ad2abb10 100644 --- a/opendaylight/sal/yang-prototype/code-generator/maven-yang-plugin/src/main/java/org/opendaylight/controller/yang2sources/plugin/YangToSourcesMojo.java +++ b/opendaylight/sal/yang-prototype/code-generator/maven-yang-plugin/src/main/java/org/opendaylight/controller/yang2sources/plugin/YangToSourcesMojo.java @@ -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: + *
    + *
  1. List yang files from {@link #yangFilesRootDir}
    2. + *
  2. Process yang files using {@link YangModelParserImpl}
    3. + *
  3. For each {@link CodeGenerator} from {@link #codeGenerators}:
    4. + *
      + *
    1. Instantiate using default constructor
      2. + *
    2. Call {@link CodeGenerator#generateSources(SchemaContext, File)}
      3. + *
    + *
+ */ @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; diff --git a/opendaylight/sal/yang-prototype/code-generator/maven-yang/src/main/java/org/opendaylight/controller/yang2sources/spi/CodeGenerator.java b/opendaylight/sal/yang-prototype/code-generator/maven-yang/src/main/java/org/opendaylight/controller/yang2sources/spi/CodeGenerator.java index 2b39320989..534c37de10 100644 --- a/opendaylight/sal/yang-prototype/code-generator/maven-yang/src/main/java/org/opendaylight/controller/yang2sources/spi/CodeGenerator.java +++ b/opendaylight/sal/yang-prototype/code-generator/maven-yang/src/main/java/org/opendaylight/controller/yang2sources/spi/CodeGenerator.java @@ -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 generateSources(SchemaContext context, File outputBaseDir); } diff --git a/opendaylight/sal/yang-prototype/code-generator/maven-yang/src/main/java/org/opendaylight/controller/yang2sources/spi/ResourceGenerator.java b/opendaylight/sal/yang-prototype/code-generator/maven-yang/src/main/java/org/opendaylight/controller/yang2sources/spi/ResourceGenerator.java index 9095155b0c..2638dc33b0 100644 --- a/opendaylight/sal/yang-prototype/code-generator/maven-yang/src/main/java/org/opendaylight/controller/yang2sources/spi/ResourceGenerator.java +++ b/opendaylight/sal/yang-prototype/code-generator/maven-yang/src/main/java/org/opendaylight/controller/yang2sources/spi/ResourceGenerator.java @@ -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 resources, File outputBaseDir); } -- 2.36.6