Normalizing package names according to

[mdsal.git] / binding2 / mdsal-binding2-spec / src / site / asciidoc / binding-2.adoc

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 e76ecdd772214725fc1d2ac52eab78a2028e424d..797750c68cb0ffb438183c592cb3badb36179acb 100644 (file)
--- a/binding2/mdsal-binding2-spec/src/site/asciidoc/binding-2.adoc
+++ b/binding2/mdsal-binding2-spec/src/site/asciidoc/binding-2.adoc
@@ -39,6 +39,8 @@ the first character of identifier, any other first character of identifier part
  \example - ReverseSolidusExample
  1example - DigitOneExample
  example1 - Example1
+ int - IntReservedKeyword
+ con - ConReservedKeyword
 
 * enum value, constant
 ** used underscore as special separator
@@ -50,6 +52,8 @@ the first character of identifier, any other first character of identifier part
  \example - REVERSE_SOLIDUS_EXAMPLE
  1example - DIGIT_ONE_EXAMPLE
  example1 - EXAMPLE1
+ int - INT_RESERVED_KEYWORD
+ con - CON_RESERVED_KEYWORD
 
 * method, variable
 ** without special separator
@@ -62,6 +66,75 @@ the first character of identifier, any other first character of identifier part
  \example - reverseSolidusExample
  1example - digitOneExample
  example1 - example1
+ int - intReservedKeyword
+ con - conReservedKeyword
+
+* package - full package name - https://docs.oracle.com/javase/tutorial/java/package/namingpkgs.html
+** parts of package name are separated by dots
+** parts of package name are converting to lower case
+** if parts of package name are reserved Java or Windows keywords, such as 'int' the suggested convention is to add an underscore to keyword
+** dash is parsed as underscore according to https://docs.oracle.com/javase/tutorial/java/package/namingpkgs.html
+
+ examples:
+ org.example* - org.exampleasterisk
+ org.example*example - org.exampleasteriskexample
+ org.example - org.reversesolidusexample
+ org.1example - org.digitoneexample
+ org.example1 - org.example1
+ org.int - org.int_
+ org.con - org.con_
+ org.foo-cont - org.foo_cont
+
+==== Special case - '-' in identifiers
+There is special case in CLASS, INTERFACE, ENUM, ENUM VALUE, CONSTANT, METHOD and VARIABLE if
+identifier contains single dash - then the converter ignores the single dash in the way of the
+non-java chars. In other way, if dash is the first or the last char in the identifier or there is
+more dashes in a row in the identifier, then these dashes are converted as non-java chars.
+
+Example:
+
+* class, enum, interface
+
+ foo-cont - FooCont
+ foo--cont - FooHyphenMinusHyphenMinusCont
+ -foo - HyphenMinusFoo
+ foo- - FooHyphenMinus
+
+* enum value, constant
+
+ foo-cont - FOO_CONT
+ foo--cont - FOO_HYPHEN_MINUS_HYPHEN_MINUS_CONT
+ -foo - HYPHEN_MINUS_FOO
+ foo- - FOO_HYPHEN_MINUS
+
+* method, variable
+
+ foo-cont - fooCont
+ foo--cont - fooHyphenMinusHyphenMinusCont
+ -foo - hyphenMinusFoo
+ foo- - fooHyphenMinus
+
+==== Special case - same class (or enum or interface) names with different camel cases
+Next special case talks about normalizing class name which already exists in package - but with
+different camel cases (foo, Foo, fOo, ...). To every next classes with same names will by added
+their actual rank (serial number), except the first one. This working for CLASS, ENUM and
+INTEFACE java identifiers. If there exist the same ENUM VALUES in ENUM (with different camel
+cases), then it's parsed with same logic like CLASSES, ENUMS and INTERFACES but according to list
+of pairs of their ENUM parent. Example:
+
+* class, enum, interface
+
+ package name org.example, class (or interface or enum) Foo - normalized to Foo
+ package name org.example, class (or interface or enum) fOo - normalized to Foo1
+
+* enum value
+
+ type enumeration {
+     enum foo;
+     enum Foo;
+ }
+ YANG enum values will be mapped to 'FOO' and 'FOO_1' Java enum values.
+
 
 === Binding Specification v2 Concepts