From: Martin Vitez Date: Fri, 15 Nov 2013 11:56:45 +0000 (+0100) Subject: Enhancement of documentation generator. X-Git-Tag: release/beryllium~719 X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?a=commitdiff_plain;h=ecc54d22a32735eaf709b2113075dac08a5f6cc7;p=mdsal.git Enhancement of documentation generator. Signed-off-by: Martin Vitez --- diff --git a/code-generator/maven-sal-api-gen-plugin/src/main/java/org/opendaylight/yangtools/yang/unified/doc/generator/GeneratorImpl.xtend b/code-generator/maven-sal-api-gen-plugin/src/main/java/org/opendaylight/yangtools/yang/unified/doc/generator/GeneratorImpl.xtend index 965fd75235..78eeaf3383 100644 --- a/code-generator/maven-sal-api-gen-plugin/src/main/java/org/opendaylight/yangtools/yang/unified/doc/generator/GeneratorImpl.xtend +++ b/code-generator/maven-sal-api-gen-plugin/src/main/java/org/opendaylight/yangtools/yang/unified/doc/generator/GeneratorImpl.xtend @@ -82,6 +82,8 @@ class GeneratorImpl { «typeDefinitions(module)» + «identities(module)» + «groupings(module)» «dataStore(module)» @@ -94,6 +96,8 @@ class GeneratorImpl { «extensions(module)» + «features(module)» + ''' @@ -104,31 +108,58 @@ class GeneratorImpl { } return '''

Type Definitions

- «list(typedefs)» - + ''' } - private def CharSequence typeDefinition(TypeDefinition type) ''' - «header(type)» - «body(type)» - «restrictions(type)» - ''' + private def identities(Module module) { + if (module.identities.empty) { + return ''; + } + return ''' +

Identities

+ + ''' + } - def groupings(Module module) { + private def groupings(Module module) { if (module.groupings.empty) { return ''; } return '''

Groupings

- «list(module.groupings)» - + ''' } @@ -215,30 +246,25 @@ class GeneratorImpl { ''' } - def CharSequence headerAndBody(SchemaNode node) ''' - «header(node)» - «body(node)» - ''' - - def header(SchemaNode type) ''' -

«type.QName.localName»

- ''' - - def body(SchemaNode definition) ''' - - «paragraphs(definition.description)» - - «definition.reference» - ''' - + def features(Module module) { + if (module.features.empty) { + return ''; + } + return ''' +

Features

- def list(Set definitions) ''' - - ''' + + ''' + } def header(Module module) '''

«module.name»

@@ -246,11 +272,11 @@ class GeneratorImpl {

Base Information

Prefix
- 
«module.prefix»
+
«pre(module.prefix)»
Namespace
- 
«module.namespace»
+
«pre(module.namespace.toString)»
Revision
-
«REVISION_FORMAT.format(module.revision)»
+
«pre(REVISION_FORMAT.format(module.revision))»
«FOR imp : module.imports BEFORE "
Imports
" »
«pre(imp.prefix)» = «pre(imp.moduleName)»
@@ -258,7 +284,6 @@ class GeneratorImpl {
''' - def process(Module module) { throw new UnsupportedOperationException("TODO: auto-generated method stub") } @@ -268,14 +293,14 @@ class GeneratorImpl { /* #################### TREE STRUCTURE #################### */ def dispatch CharSequence tree(Module module) ''' «strong("module " + module.name)» - «module.childNodes.childrenToTree» + «module.childNodes.tree» ''' def dispatch CharSequence tree(DataNodeContainer node) ''' «IF node instanceof SchemaNode» «(node as SchemaNode).nodeName» «ENDIF» - «node.childNodes.childrenToTree» + «node.childNodes.tree» ''' def dispatch CharSequence tree(DataSchemaNode node) ''' @@ -284,10 +309,10 @@ class GeneratorImpl { def dispatch CharSequence tree(ListSchemaNode node) ''' «node.nodeName» - «node.childNodes.childrenToTree» + «node.childNodes.tree» ''' - private def CharSequence childrenToTree(Collection childNodes) ''' + def dispatch CharSequence tree(Collection childNodes) ''' «IF childNodes !== null && !childNodes.empty»
    «FOR child : childNodes» @@ -305,7 +330,7 @@ class GeneratorImpl { def dispatch CharSequence tree(AugmentationSchema augment) '''
      - «listItem("Description", augment.description)» + «listItem(augment.description)» «listItem("Reference", augment.reference)» «IF augment.whenCondition !== null» «listItem("When", augment.whenCondition.toString)» @@ -315,38 +340,24 @@ class GeneratorImpl {
    • Child nodes - «augment.childNodes.childrenToTree» + «augment.childNodes.tree»
    ''' - private def CharSequence pathToTree(List path) ''' - «IF path !== null && !path.empty» -
      - «FOR pathElement : path» -
    • - «pathElement.namespace» «pathElement.localName» -
      • - «ENDFOR» -
    - «ENDIF» - ''' - def dispatch CharSequence tree(NotificationDefinition notification) '''
      - «listItem("Description", notification.description)» - «listItem("Reference", notification.reference)» + «notification.descAndRef»
    • Child nodes - «notification.childNodes.childrenToTree» + «notification.childNodes.tree»
    ''' def dispatch CharSequence tree(RpcDefinition rpc) '''
      - «listItem("Description", rpc.description)» - «listItem("Reference", rpc.reference)» + «rpc.descAndRef»
    • «rpc.input.tree»
      • @@ -358,13 +369,13 @@ class GeneratorImpl { def dispatch CharSequence tree(ExtensionDefinition ext) '''
        - «listItem("Description", ext.description)» - «listItem("Reference", ext.reference)» + «ext.descAndRef» «listItem("Argument", ext.argument)»
      ''' + /* #################### RESTRICTIONS #################### */ private def restrictions(TypeDefinition type) ''' «type.toLength» @@ -407,7 +418,7 @@ class GeneratorImpl { def toLengthStmt(Collection lengths) ''' «IF lengths != null && !lengths.empty» - «strong("Length restrictions")» + «listItem("Length restrictions")»
        «FOR length : lengths»
      • @@ -424,7 +435,7 @@ class GeneratorImpl { def toRangeStmt(Collection ranges) ''' «IF ranges != null && !ranges.empty» - «strong("Range restrictions")» + «listItem("Range restrictions")»
          «FOR range : ranges»
        • @@ -442,21 +453,24 @@ class GeneratorImpl { /* #################### UTILITY #################### */ - def strong(String str) ''' - «str» - ''' + private def strong(String str) '''«str»''' + private def italic(String str) '''«str»''' + private def pre(String str) '''
          «str»
          ''' - def italic(String str) ''' - «str» + def CharSequence descAndRef(SchemaNode node) ''' + «listItem(node.description)» + «listItem("Reference", node.reference)» ''' - def pre(String string) '''
          «string»
          ''' - - def paragraphs(String body) ''' -

          «body»

          + private def listItem(String value) ''' + «IF value !== null && !value.empty» +
        • + «value» +
          • + «ENDIF» ''' - def listItem(String name, String value) ''' + private def listItem(String name, String value) ''' «IF value !== null && !value.empty»
        • «name» @@ -469,6 +483,18 @@ class GeneratorImpl { «ENDIF» ''' + private def CharSequence pathToTree(List path) ''' + «IF path !== null && !path.empty» +
            + «FOR pathElement : path» +
          • + «pathElement.namespace» «pathElement.localName» +
            • + «ENDFOR» +
          + «ENDIF» + ''' + def dispatch addedByInfo(SchemaNode node) ''' ''' @@ -488,7 +514,7 @@ class GeneratorImpl { } } - def nodeName(SchemaNode node) ''' + def dispatch nodeName(SchemaNode node) ''' «IF node.isAddedBy» «italic(node.QName.localName)»«node.addedByInfo» «ELSE» @@ -496,7 +522,7 @@ class GeneratorImpl { «ENDIF» ''' - def nodeName(ListSchemaNode node) ''' + def dispatch nodeName(ListSchemaNode node) ''' «IF node.isAddedBy» «italic(node.QName.localName)» «IF node.keyDefinition !== null && !node.keyDefinition.empty»«node.listKeys»«ENDIF»«node.addedByInfo» «ELSE» diff --git a/code-generator/maven-sal-api-gen-plugin/src/test/java/org/opendaylight/yangtools/yang/unified/doc/generator/maven/DocGenTest.java b/code-generator/maven-sal-api-gen-plugin/src/test/java/org/opendaylight/yangtools/yang/unified/doc/generator/maven/DocGenTest.java index 59290bf828..7bf8f3ea6c 100644 --- a/code-generator/maven-sal-api-gen-plugin/src/test/java/org/opendaylight/yangtools/yang/unified/doc/generator/maven/DocGenTest.java +++ b/code-generator/maven-sal-api-gen-plugin/src/test/java/org/opendaylight/yangtools/yang/unified/doc/generator/maven/DocGenTest.java @@ -9,45 +9,34 @@ import java.util.Arrays; import java.util.List; import java.util.Set; +import org.junit.After; import org.junit.Before; -import org.junit.BeforeClass; import org.junit.Test; -import org.opendaylight.yangtools.sal.binding.generator.api.BindingGenerator; -import org.opendaylight.yangtools.sal.binding.generator.impl.BindingGeneratorImpl; import org.opendaylight.yangtools.yang.model.api.Module; import org.opendaylight.yangtools.yang.model.api.SchemaContext; import org.opendaylight.yangtools.yang.parser.impl.YangParserImpl; import org.opendaylight.yangtools.yang2sources.spi.CodeGenerator; public class DocGenTest { - public static final String FS = File.separator; - static final String BASE_PKG = "org.opendaylight.yang.gen.v1"; - - static final String TEST_PATH = "target" + FS + "test"; - static final File TEST_DIR = new File(TEST_PATH); - - static final File GENERATOR_OUTPUT_DIR = new File(TEST_PATH); - static final String COMPILER_OUTPUT_PATH = TEST_PATH + FS + "bin"; - static final File COMPILER_OUTPUT_DIR = new File(COMPILER_OUTPUT_PATH); - + private static final String TEST_PATH = "target" + FS + "test" + FS + "site"; + private static final File GENERATOR_OUTPUT_DIR = new File(TEST_PATH); + private YangParserImpl parser; - protected YangParserImpl parser; - protected BindingGenerator bindingGenerator; - - @BeforeClass - public static void createTestDirs() { - if (TEST_DIR.exists()) { - deleteTestDir(TEST_DIR); + @Before + public void init() { + if (GENERATOR_OUTPUT_DIR.exists()) { + deleteTestDir(GENERATOR_OUTPUT_DIR); } assertTrue(GENERATOR_OUTPUT_DIR.mkdirs()); - assertTrue(COMPILER_OUTPUT_DIR.mkdirs()); + parser = new YangParserImpl(); } - @Before - public void init() { - parser = new YangParserImpl(); - bindingGenerator = new BindingGeneratorImpl(); + @After + public void cleanUp() { + if (GENERATOR_OUTPUT_DIR.exists()) { + deleteTestDir(GENERATOR_OUTPUT_DIR); + } } @Test @@ -57,11 +46,9 @@ public class DocGenTest { final SchemaContext context = parser.resolveSchemaContext(modulesToBuild); final CodeGenerator generator = new DocumentationGeneratorImpl(); generator.generateSources(context, GENERATOR_OUTPUT_DIR, modulesToBuild); - - } - static List getSourceFiles(String path) throws FileNotFoundException { + private static List getSourceFiles(String path) throws FileNotFoundException { final String resPath = DocGenTest.class.getResource(path).getPath(); final File sourcesDir = new File(resPath); if (sourcesDir.exists()) { @@ -77,8 +64,7 @@ public class DocGenTest { } } - - static void deleteTestDir(File file) { + private static void deleteTestDir(File file) { if (file.isDirectory()) { File[] filesToDelete = file.listFiles(); if (filesToDelete != null) { @@ -91,4 +77,5 @@ public class DocGenTest { throw new RuntimeException("Failed to clean up after test"); } } + } diff --git a/code-generator/maven-sal-api-gen-plugin/src/test/resources/doc-gen/network-topology@2013-07-12.yang b/code-generator/maven-sal-api-gen-plugin/src/test/resources/doc-gen/network-topology@2013-07-12.yang index 835288c3e4..fb18be46bc 100644 --- a/code-generator/maven-sal-api-gen-plugin/src/test/resources/doc-gen/network-topology@2013-07-12.yang +++ b/code-generator/maven-sal-api-gen-plugin/src/test/resources/doc-gen/network-topology@2013-07-12.yang @@ -108,8 +108,10 @@ module network-topology { typedef x { type binary { - length 5..10; + length 5..10|15..20|25..30; } + description "x type description"; + reference "x type reference"; } typedef y { @@ -118,6 +120,20 @@ module network-topology { } } + identity crypto-alg { + description "Base identity from which all crypto algorithms are derived."; + } + + identity des { + base "crypto-alg"; + description "DES crypto algorithm"; + } + + identity des3 { + base "crypto-alg"; + description "Triple DES crypto algorithm"; + } + grouping tp-attributes { description "The data objects needed to define a termination point. @@ -332,8 +348,18 @@ module network-topology { } anyxml reporting-entity; container severity { - leaf id { - type string; + list links { + container endpoints { + leaf start { + type x; + } + leaf end { + type y; + } + } + leaf id { + type string; + } } } } @@ -374,6 +400,8 @@ module network-topology { } rpc rock-the-house { + description "This statement is used to define a NETCONF RPC operation."; + reference "http://tools.ietf.org/html/rfc6020#section-7.13"; input { leaf zip-code { type string; @@ -394,4 +422,11 @@ module network-topology { argument "name"; } + feature local-storage { + description + "This feature means the device supports local + storage (memory, flash or disk) that can be used to + store syslog messages."; + } + }