From 127be8319e8b153ddf9da430435b6b1f8601e492 Mon Sep 17 00:00:00 2001
From: Martin Ciglan <mciglan@cisco.com>
Date: Mon, 15 Aug 2016 15:19:42 +0200
Subject: [PATCH] BUG-1411: MDSAL Binding2 Spec - comments/feedback fixed

- based on review by Martin Sunal

Change-Id: I7da6e1c35ffed18fe62c7d4092b1eb8557913762
Signed-off-by: Martin Sunal <msunal@cisco.com>
Signed-off-by: Martin Ciglan <mciglan@cisco.com>
(cherry picked from commit a303d7a4a894d7ae9c14e0e8924388de57f08c95)
---
 .../src/site/asciidoc/binding-2.adoc          | 57 ++++++++++++-------
 1 file changed, 38 insertions(+), 19 deletions(-)

diff --git a/binding2/mdsal-binding2-spec/src/site/asciidoc/binding-2.adoc b/binding2/mdsal-binding2-spec/src/site/asciidoc/binding-2.adoc
index 1e344251cf..5649b083df 100644
--- a/binding2/mdsal-binding2-spec/src/site/asciidoc/binding-2.adoc
+++ b/binding2/mdsal-binding2-spec/src/site/asciidoc/binding-2.adoc
@@ -30,7 +30,7 @@ Builder::
   is not used directly, but rather via <<TreeChildNode>>. See <<instantiated-data-tree-rules>>
   for more information.
 <<TreeRoot>>::
-  Represents virtual root of instantiated data tree node.
+  Represents virtual root of instantiated data tree.
 <<TreeChildNode>>::
   Represents node, which is part of instantiated data tree and is not root of
   data tree.
@@ -102,8 +102,7 @@ YANG namespace::
 Binding namespace::
   Naming space introduced by Binding Specification for additional properties
   and functionality of Binding Specification. This namespaces needs to be separate
-  from YANG namespaces in order to not have naming conflict with YANG-derived
-  names.
+  from YANG namespaces in order to not have naming conflict with YANG-derived.
 
 
 Binding Specification v2 uses following namespaces:
@@ -351,15 +350,22 @@ container example-outter {
 [source,yang]
 ----
 list foo {
-    key identifier;
+    key identifier key fookey;
     leaf identifier {
         type union {
             type string;
         }
     }
+
+    leaf key {
+        type string;
+    }
+
+    leaf fookey {
+        type string;
+    }
 }
 ----
-
 [uml, file="list-Keyed.png"]
 --
 set namespaceSeparator none
@@ -370,10 +376,18 @@ interface data.Foo {
 interface key.foo.FooIdentifier {
 }
 
+interface key.foo.FooKey {
+}
+
+interface key.foo.FooFooKey {
+}
+
 interface type.foo.identifier.IdentifierUnion {
 }
 
 data.Foo o- key.foo.FooIdentifier
+data.Foo o- key.foo.FooKey
+data.Foo o- key.foo.FooFooKey
 key.foo.FooIdentifier o- type.foo.identifier.IdentifierUnion
 --
 
@@ -423,7 +437,7 @@ data.top.base.Foo -u-|> Case
 data.top.base.Bar -u-|> Case
 
 data.top.base.Foo -u-|> data.top.Base
-data.top.base.Bar -u-|> data.top.base.Foo
+data.top.base.Bar -u-|> data.top.Base
 
 data.Top o- data.top.Base
 data.top.base.Foo o- data.top.base.foo.Foo
@@ -511,13 +525,13 @@ FIXME: Here should be Augmentable & Instantied & ChildDataNode
 === `grouping` Statement
 
 * `grouping` statement is represented by `interface`
-** class name is generated according to <<class-naming>> with suffix `Grouping`
+** interface name is generated according to <<class-naming>> with suffix `Grouping`
 * Representations of `grouping` statements are generated into <<grouping-namespace>>
-* data schema nodes under grouping are represented by `interface` and are generated
-  into <<grouping-namespace>>
+* schema nodes under grouping are represented by `interface` and are generated
+  into <<grouping-namespace>> + name of grouping
 ** getters (accessors) from parent nodes are generated according to <<accessor-rules>>
 ** class name is generated according to <<class-naming>> with suffix `Data`
-** data schema nodes does not follow <<instantiated-data-tree-rules>>, these interfaces
+** schema nodes does not follow <<instantiated-data-tree-rules>>, these interfaces
    are used only in instantiated data tree.
 
 .Simple Grouping
@@ -550,7 +564,16 @@ grp.SimpleGrouping o- grp.simple.FooData
 
 Representations of data node substatements are generated according to rules
 described in <<data-node-rules>> with following changes:
-
+////
+MS: proposed interface names:
+case - <NodeName>Case
+choice - <<NodeName>Choice
+container, list - <NodeName>
+////
+////
+MC: I would keep Data suffix, but idea about distinguishing cases and choices
+is to think about
+////
 * Interface names for `case`, `choice`, `container` and `list`, is suffixed by
   `Data` suffix, in order to not conflict with same named groupings inside same
   package
@@ -604,7 +627,6 @@ container top {
   uses simple;
 }
 ----
-
 [uml, file="grouping2.png"]
 --
 set namespaceSeparator none
@@ -637,9 +659,7 @@ are based on <<instantiated-data-tree-rules>>
 .YANG Snippet
 [source, yang]
 ----
-set namespaceSeparator none
 grouping with-inner {
-
   grouping inner {
     container cont;
   }
@@ -807,9 +827,8 @@ augment statement is defined
   augmentation is generated, child data nodes are generated by rules for
   <<instantiated-data-node-rules>>.
   See <<augment-other-module>> for details & examples.
-
-`augment` statement targets only instantiated data nodes, so child data node
-representation are always ge
+`augment` statement targets only instantiated data nodes, so child data nodes
+representation is always generated.
 
 [[augment-same-module]]
 ==== Augmentation target in same module
@@ -1071,6 +1090,6 @@ grouping nodes {
 }
 
 ----
-grouping key.grp.nodes.node.nodeidentifier
+grouping key.grp.nodes.node.<nodeidentifier>
 
-instantiated key.data.nodes.node.nodeidentifier
\ No newline at end of file
+instantiated key.data.nodes.node.<nodeidentifier>
-- 
2.36.6