Add Binding Specification v2 Documentation

This patch adds description to Binding Specification v2 documentation
how identifiers derived from YANGs are being treated, eventually resolving
to compilable generated code. These issues with compilation
using Binding specification v1 have been originally tracked in following
bugs:

Bug: 2332
Bug: 2641
Bug: 2791
Change-Id: Ib68de210cd72a6823edfc0f75577c1f9ff0f0b78
Signed-off-by: Martin Ciglan <mciglan@cisco.com>

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 5649b083dfc20c2cc838820736bbe092bb70638f..e76ecdd772214725fc1d2ac52eab78a2028e424d 100644 (file)
--- a/binding2/mdsal-binding2-spec/src/site/asciidoc/binding-2.adoc
+++ b/binding2/mdsal-binding2-spec/src/site/asciidoc/binding-2.adoc
@@ -20,6 +20,49 @@ Transfer Object::
 Builder::
   builder
 
+=== YANG Identifiers Mapping
+
+Every non-Java char in identifier is converted to Java char by its unicode name http://docs.oracle.com/javase/specs/jls/se8/html/jls-3.html#jls-3.8
+JAVA SE SPECIFICATIONS - Identifiers. This mapping solves various issues from Binding Specification v1, which led to compilation issues.
+
+There are special types of mapping non-java chars to original identifiers according to specific Java type:
+
+* class, enum, interface
+
+** without special separator
+the first character of identifier, any other first character of identifier part mapped by
+** non-Java char name from unicode and char in identifier behind non-java char name are converting to upper case
+
+ examples:
+ example* - ExampleAsterisk
+ example*example - ExampleAserisksExample
+ \example - ReverseSolidusExample
+ 1example - DigitOneExample
+ example1 - Example1
+
+* enum value, constant
+** used underscore as special separator
+** converted identifier to upper case
+
+ examples:
+ example* - EXAMPLE_ASTERISK
+ example*example - EXAMPLE_ASTERISK_EXAMPLE
+ \example - REVERSE_SOLIDUS_EXAMPLE
+ 1example - DIGIT_ONE_EXAMPLE
+ example1 - EXAMPLE1
+
+* method, variable
+** without special separator
+** the first character of identifier is converting to lower case
+** any other first character of identifier part mapped by non-Java char name from unicode and char in identifier behind non-java char name are converting to upper case
+
+ examples:
+ example* - exampleAsterisk
+ example*example - exampleAserisksExample
+ \example - reverseSolidusExample
+ 1example - digitOneExample
+ example1 - example1
+
 === Binding Specification v2 Concepts
 
 <<Instantiable>>::