From: Martin Vitez Date: Wed, 18 Dec 2013 11:42:49 +0000 (+0100) Subject: Documentation generator improvements. X-Git-Tag: release/beryllium~671^2 X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?a=commitdiff_plain;h=0ea8b05b970322b9772eac34acbd95f64789cb6a;p=mdsal.git Documentation generator improvements. Updated generation of augment target path. Updated generation of notificiations. Change-Id: I477cb9a1baa654792bea7ad21a0edc653538e862 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 e7323720b2..b910609042 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 @@ -7,7 +7,6 @@ import org.opendaylight.yangtools.yang.model.api.Module import java.io.IOException import java.util.HashSet import java.io.BufferedWriter -import java.io.OutputStream; import java.io.OutputStreamWriter; import org.opendaylight.yangtools.yang.model.api.DataSchemaNode import org.opendaylight.yangtools.yang.model.api.ListSchemaNode @@ -27,7 +26,6 @@ import org.opendaylight.yangtools.yang.model.api.NotificationDefinition import org.opendaylight.yangtools.yang.model.api.DataNodeContainer import org.slf4j.LoggerFactory import org.slf4j.Logger -import org.opendaylight.yangtools.yang.model.api.AugmentationSchema import java.util.List import org.opendaylight.yangtools.yang.common.QName import org.opendaylight.yangtools.yang.model.api.RpcDefinition @@ -46,12 +44,10 @@ import org.opendaylight.yangtools.yang.data.api.InstanceIdentifier import org.opendaylight.yangtools.yang.data.api.InstanceIdentifier.NodeIdentifierWithPredicates import java.util.LinkedHashMap import org.opendaylight.yangtools.yang.data.api.InstanceIdentifier.NodeIdentifier -import com.google.common.collect.FluentIterable import org.opendaylight.yangtools.yang.model.api.LeafSchemaNode -import org.opendaylight.yangtools.yang.model.api.LeafListSchemaNode -import java.net.URLEncoder -import javax.swing.text.StyledEditorKit.ForegroundAction - +import org.opendaylight.yangtools.yang.model.api.LeafListSchemaNode import java.util.HashMap +import org.opendaylight.yangtools.yang.model.api.AnyXmlSchemaNode + class GeneratorImpl { File path @@ -66,18 +62,18 @@ class GeneratorImpl { path.mkdirs(); val it = new HashSet; for (module : modulesToGen) { - add(module.generateDocumentation()); + add(generateDocumentation(module, context)); } return it; } - def generateDocumentation(Module module) { + def generateDocumentation(Module module, SchemaContext ctx) { val destination = new File(path, '''Â«module.nameÂ».html''') try { val fw = new OutputStreamWriter(CTX.newFileOutputStream(destination)) val bw = new BufferedWriter(fw) currentModule = module; - bw.append(module.generate); + bw.append(generate(module, ctx)); bw.close(); fw.close(); } catch (IOException e) { @@ -86,19 +82,19 @@ class GeneratorImpl { return destination; } - def generate(Module module) ''' + def generate(Module module, SchemaContext ctx) ''' Â«module.nameÂ» - Â«module.bodyÂ» + Â«body(module, ctx)Â» ''' - def body(Module module) ''' + def body(Module module, SchemaContext ctx) ''' Â«header(module)Â» Â«typeDefinitions(module)Â» @@ -113,7 +109,7 @@ class GeneratorImpl { Â«notifications(module)Â» - Â«augmentations(module)Â» + Â«augmentations(module, ctx)Â» Â«rpcs(module)Â» @@ -136,7 +132,7 @@ class GeneratorImpl {

Â«strong("typedef " + typedef.QName.localName)Â»

- Â«typedef.descAndRefÂ» + Â«typedef.descAndRefLiÂ» Â«typedef.restrictionsÂ»

@@ -156,7 +152,7 @@ class GeneratorImpl {

Â«strong("identity " + identity.QName.localName)Â»

Â«strong("grouping " + grouping.QName.localName)Â»

- augment - Â«augment.augmentationInfo(InstanceIdentifier.builder().toInstance())Â» - Â«augment.childNodes.printChildren(2,InstanceIdentifier.builder().toInstance())Â» +
Target [Â«schemaPathAsRestconfPath(module, augment.targetPath, context)Â»]
+ Â«augment.descriptionÂ» + Â«IF augment.reference !== nullÂ» + Reference Â«augment.referenceÂ» + Â«ENDIFÂ» + Â«IF augment.whenCondition !== nullÂ» + When Â«augment.whenCondition.toStringÂ» + Â«ENDIFÂ» + Â«augment.childNodes.printChildren(3,InstanceIdentifier.builder().toInstance())Â»

Notifications

Â«notificationdef.nodeNameÂ»

RPC Definitions

Â«ext.nodeNameÂ»
Â«strong("feature " + feature.QName.localName)Â»

Â«module.nameÂ»

Base Information

Prefix: Â«pre(module.namespace.toString)Â»
Revision: Â«pre(REVISION_FORMAT.format(module.revision))Â»
Imports: Â«code(imp.prefix)Â» = Â«code(imp.moduleName)Â»

Â«stringÂ»

nodes,InstanceIdentifier path) '''

Child nodes

nodes, int level, InstanceIdentifier path) { + val anyxmlNodes = nodes.filter(AnyXmlSchemaNode) val leafNodes = nodes.filter(LeafSchemaNode) val leafListNodes = nodes.filter(LeafListSchemaNode) val choices = nodes.filter(ChoiceNode) @@ -358,8 +363,12 @@ class GeneratorImpl { val containers = nodes.filter(ContainerSchemaNode) val lists = nodes.filter(ListSchemaNode) return ''' + Â«IF ((anyxmlNodes.size + leafNodes.size + leafListNodes.size + containers.size + lists.size) > 0)Â»

Direct children

+ Â«FOR childNode : anyxmlNodesÂ» + Â«childNode.printShortInfo(level,path)Â» + Â«ENDFORÂ» Â«FOR childNode : leafNodesÂ» Â«childNode.printShortInfo(level,path)Â» Â«ENDFORÂ» @@ -373,7 +382,8 @@ class GeneratorImpl { Â«childNode.printShortInfo(level,path)Â» Â«ENDFORÂ» - + Â«ENDIFÂ» + Â«IF !path.path.emptyÂ»

XML example

Â«nodes.xmlExample(path.path.last.nodeType,path)Â» @@ -394,53 +404,68 @@ class GeneratorImpl { ''' } - + def CharSequence xmlExample(Set nodes, QName name,InstanceIdentifier path) '''

         Â«xmlExampleTag(name,nodes.xmplExampleTags(path))Â»

''' - + def CharSequence xmplExampleTags(Set nodes, InstanceIdentifier identifier) ''' Â«FOR node : nodesÂ» Â«node.asXmlExampleTag(identifier)Â» Â«ENDFORÂ» - + ''' - + private def dispatch CharSequence asXmlExampleTag(LeafSchemaNode node, InstanceIdentifier identifier) ''' Â«node.QName.xmlExampleTag("...")Â» ''' - + private def dispatch CharSequence asXmlExampleTag(LeafListSchemaNode node, InstanceIdentifier identifier) '''  Â«node.QName.xmlExampleTag("...")Â» ''' - + private def dispatch CharSequence asXmlExampleTag(ContainerSchemaNode node, InstanceIdentifier identifier) '''  Â«node.QName.xmlExampleTag("...")Â» ''' - - + + private def dispatch CharSequence asXmlExampleTag(ListSchemaNode node, InstanceIdentifier identifier) '''   Â«node.QName.xmlExampleTag("...")Â» ''' - - + + private def dispatch CharSequence asXmlExampleTag(DataSchemaNode node, InstanceIdentifier identifier) ''' ''' - - + + def xmlExampleTag(QName name, CharSequence data) { return '''<Â«name.localNameÂ» xmlns="Â«name.namespaceÂ»">Â«dataÂ»</Â«name.localNameÂ»>''' } - + + def header(int level,QName name) '''Â«name.localNameÂ»''' + + + def header(int level,InstanceIdentifier name) ''' + + Â«FOR cmp : name.path SEPARATOR "/"Â»Â«cmp.nodeType.localNameÂ»Â«ENDFORÂ» + + ''' + + + + private def dispatch CharSequence printInfo(DataSchemaNode node, int level, InstanceIdentifier path) ''' + Â«header(level+1,node.QName)Â» + ''' + private def dispatch CharSequence printInfo(ContainerSchemaNode node, int level, InstanceIdentifier path) ''' Â«val newPath = path.append(node)Â» Â«header(level,newPath)Â» @@ -452,17 +477,7 @@ class GeneratorImpl { Â«node.childNodes.printChildren(level,newPath)Â» ''' - - def header(int level,QName name) '''Â«name.localNameÂ»''' - - - def header(int level,InstanceIdentifier name) - ''' - - Â«FOR cmp : name.path SEPARATOR "/"Â»Â«cmp.nodeType.localNameÂ»Â«ENDFORÂ» - ''' - - + private def dispatch CharSequence printInfo(ListSchemaNode node, int level, InstanceIdentifier path) ''' Â«val newPath = path.append(node)Â» Â«header(level,newPath)Â» @@ -484,26 +499,34 @@ class GeneratorImpl { Â«node.childNodes.printChildren(level,path)Â» ''' + + def CharSequence printShortInfo(ContainerSchemaNode node, int level, InstanceIdentifier path) { val newPath = path.append(node); return '''

Â«strong(localLink(newPath,node.QName.localName))Â» (container)

''' } - + def CharSequence printShortInfo(ListSchemaNode node, int level, InstanceIdentifier path) { val newPath = path.append(node); return '''

Â«strong(localLink(newPath,node.QName.localName))Â» (list)

''' } - + + def CharSequence printShortInfo(AnyXmlSchemaNode node, int level, InstanceIdentifier path) { + return ''' +

Â«strong((node.QName.localName))Â» (anyxml)

+ ''' + } + def CharSequence printShortInfo(LeafSchemaNode node, int level, InstanceIdentifier path) { return '''

Â«strong((node.QName.localName))Â» (leaf)

''' } - + def CharSequence printShortInfo(LeafListSchemaNode node, int level, InstanceIdentifier path) { return '''

Â«strong((node.QName.localName))Â» (leaf-list)

@@ -513,14 +536,14 @@ class GeneratorImpl { def CharSequence localLink(InstanceIdentifier identifier, CharSequence text) ''' Â«textÂ» ''' - - + + private def dispatch InstanceIdentifier append(InstanceIdentifier identifier, ContainerSchemaNode node) { val pathArguments = new ArrayList(identifier.path) pathArguments.add(new NodeIdentifier(node.QName)); return new InstanceIdentifier(pathArguments); } - + private def dispatch InstanceIdentifier append(InstanceIdentifier identifier, ListSchemaNode node) { val pathArguments = new ArrayList(identifier.path) val keyValues = new LinkedHashMap(); @@ -532,12 +555,12 @@ class GeneratorImpl { pathArguments.add(new NodeIdentifierWithPredicates(node.QName,keyValues)); return new InstanceIdentifier(pathArguments); } - - + + def asXmlPath(InstanceIdentifier identifier) { return ""; } - + def asRestconfPath(InstanceIdentifier identifier) { val it = new StringBuilder(); append(currentModule.name) @@ -556,17 +579,57 @@ class GeneratorImpl { } } } - + return it.toString; } - - - private def dispatch CharSequence printInfo(DataSchemaNode node, int level, InstanceIdentifier path) ''' - Â«header(level+1,node.QName)Â» - ''' - + private def String schemaPathAsRestconfPath(Module module, SchemaPath schemaPath, SchemaContext ctx) { + val Map imports = new HashMap(); + for (mImport : module.imports) { + imports.put(mImport.prefix, mImport.moduleName) + } + val List path = schemaPath.path + val StringBuilder pathString = new StringBuilder() + if (schemaPath.absolute) { + pathString.append("/") + } + + val QName qname = path.get(0) + var Object parent = ctx.findModuleByNamespaceAndRevision(qname.namespace, qname.revision) + + for (name : path) { + if (parent instanceof DataNodeContainer) { + var SchemaNode node = (parent as DataNodeContainer).getDataChildByName(name) + if (node == null && (parent instanceof Module)) { + val notifications = (parent as Module).notifications; + for (notification : notifications) { + if (notification.QName.localName.equals(name.localName)) { + node = notification + } + } + } + + if (!(node instanceof ChoiceNode) && !(node instanceof ChoiceCaseNode)) { + var String prefix = node.QName.prefix + var String moduleName + if (prefix == null || "".equals(prefix) || prefix.equals(module.prefix)) { + moduleName = module.name + } else { + moduleName = imports.get(prefix) + } + pathString.append(moduleName) + pathString.append(":") + pathString.append(node.QName.localName) + pathString.append("/") + } + parent = node + } else if (parent instanceof ChoiceNode) { + parent = (parent as ChoiceNode).getCaseNodeByName(qname.localName) + } + } + return pathString.toString; + } def CharSequence childNodesInfoTree(Map childNodes) ''' @@ -583,7 +646,7 @@ class GeneratorImpl { Â«code(path)Â» Â«IF node !== nullÂ»

- Â«node.descAndRefÂ» + Â«node.descAndRefLiÂ» Â«ENDIFÂ» Â«ENDIFÂ» @@ -605,36 +668,9 @@ class GeneratorImpl { [Â«FOR key : node.keyDefinition SEPARATOR " "Â»Â«key.localNameÂ»Â«ENDFORÂ»] ''' - private def CharSequence augmentationInfo(AugmentationSchema augment, InstanceIdentifier path) ''' -

- Path Â«augment.targetPath.path.pathToTreeÂ» -
- Child nodes - Â«augment.childNodes.treeSet(path)Â» -

- ''' - - private def CharSequence notificationInfo(NotificationDefinition notification,InstanceIdentifier path) ''' -

- Child nodes - Â«notification.childNodes.treeSet(path)Â» -

- ''' - private def CharSequence rpcInfo(RpcDefinition rpc,InstanceIdentifier path) '''

Â«rpc.input.tree(path)Â»

''' - private def CharSequence extensionInfo(ExtensionDefinition ext, InstanceIdentifier path) ''' + private def CharSequence extensionInfo(ExtensionDefinition ext) '''

- Â«ext.descAndRefÂ» + Â«ext.descAndRefLiÂ» Â«listItem("Argument", ext.argument)Â» ''' @@ -737,11 +773,18 @@ class GeneratorImpl { private def italic(CharSequence str) '''Â«strÂ»''' private def pre(CharSequence str) '''

Â«strÂ»

''' - def CharSequence descAndRef(SchemaNode node) ''' + def CharSequence descAndRefLi(SchemaNode node) ''' Â«listItem(node.description)Â» Â«listItem("Reference", node.reference)Â» ''' + def CharSequence descAndRef(SchemaNode node) ''' + Â«node.descriptionÂ» + Â«IF node.reference !== nullÂ» + Reference Â«node.referenceÂ» + Â«ENDIFÂ» + ''' + private def listItem(String value) ''' Â«IF value !== null && !value.emptyÂ»

@@ -753,12 +796,7 @@ class GeneratorImpl { private def listItem(String name, String value) ''' Â«IF value !== null && !value.emptyÂ»

- Â«nameÂ» -

- Â«valueÂ» -

+ Â«nameÂ»: Â«valueÂ»

Â«ENDIFÂ» ''' @@ -808,18 +846,6 @@ class GeneratorImpl { } } - private def CharSequence pathToTree(List path) ''' - Â«IF path !== null && !path.emptyÂ» -

- Â«pathElement.namespaceÂ» Â«pathElement.localNameÂ» -

- Â«ENDIFÂ» - ''' - private def dispatch addedByInfo(SchemaNode node) ''' '''

Target [Â«schemaPathAsRestconfPath(module, augment.targetPath, context)Â»]