Axiom: Added documentation to Axiom language

Signed-off-by: Tony Tkacik <tonydamage@gmail.com>

infra/axiom/src/main/resources/axiom-lang.axiom

@@ -4,7 +4,7 @@ model axiom-lang {
 
     root model {
         documentation """
-            Declares a new axiom model.
+            Declaration of Axiom model.
         """;
         type AxiomModel;
     }
@@ -14,44 +14,61 @@ model axiom-lang {
 
         item namespace {
             type string;
+            documentation """
+                Namespace of model.
+            """;
         }
 
         item version {
-            type string;
+            type SemanticVersion;
+            documentation """
+                Version of model.
+
+                Model versioning follows Semantic Versioning 2.0.
+            """;
         }
 
         item import {
             type AxiomImportDeclaration;
+            documentation """
+                Declaration of model imports.
+
+                Type definitions from imported models are referencable and 
+                visible to all definition contained in this model.
+            """;
         }
 
         item root {
             documentation """
-                Defines allowed root for serialized documents
-                modeled by Axiom language.
+                Defines allowed root type for value serialization / deserialization.
             """;
             type AxiomRootDefinition;
         }
 
         item type {
             type AxiomTypeDefinition;
             documentation """
-                Type Declaration
-
-                type statement declares a new global type, which is available
-                to model items.
+                Declaration of a type. This type is visible to models
+                importing parent model namespace.
             """;
         }
 
         item mixin {
             type AxiomMixinDefinition;
             documentation """
-                Declares a new global mixin, a set of reusable item
+                Declaration of mixin, a set of reusable item
                 definitions, which can be used in type definitions.
             """;
         }
 
+        // FIXME: should be augmentation
         item extension {
             type AxiomExtensionDefinition;
+            documentation """
+                Declaration of augmentation. Augmentation adds new items
+                to already existing type, which can be defined in other
+                models (namespaces).
+            """;
         }
     }
 
@@ -89,12 +106,13 @@ model axiom-lang {
         item since {
             type SemanticVersion;
         }
-        //item status {
-        //    documentation """
-        //        Status of definition, could be experimental, stable, deprecated.
-        //        """;
-        //    type string;
-        //}
+
+        item status {
+            type string;
+            documentation """
+                Status of definition, could be experimental, stable, deprecated.
+              """;
+        }
     }
 
     type AxiomIdentifierDefinition {
@@ -115,6 +133,11 @@ model axiom-lang {
 
     type AxiomTypeDefinition {
         extends AxiomBaseDefinition;
+        documentation """
+            Definition of value type.
+
+            Defines type name, type supertype and set of value items.
+        """;
 
         identifier name {
             scope global;
@@ -123,18 +146,38 @@ model axiom-lang {
 
         item argument {
             type AxiomIdentifier;
+            documentation """
+                Name of item, which is target of short-form value declaration.
+            """;
+            minOccurs 0;
+            maxOccurs 1;
         }
 
+        // FIXME: should be inherit
         item extends {
             type AxiomTypeReference;
+            documentation """
+                Reference to super type definition, which is subtyped by this type.
+            """;
+            minOccurs 0;
+            maxOccurs 1;
         }
 
+        // FIXME: should be use
         item uses {
             type AxiomTypeReference;
+            documentation """
+                Reference to mixin, from which this type definition reuses item definitions.
+            """;
+            minOccurs 0;
         }
 
         item identifier {
             type AxiomIdentifierDefinition;
+            documentation """
+                Definition of identifiers of this type.
+            """;
+            minOccurs 0;
         }
 
         // TODO reconsider this - strictly speaking this is part of "global type+item definition combo"
@@ -144,61 +187,94 @@ model axiom-lang {
 
         item item {
             type AxiomItemDefinition;
+            documentation """
+                Definition of child items
+            """;
+            minOccurs 0;
         }
     }
 
+    // FIXME: Should be AxiomName
     type AxiomIdentifier {
+        documentation """
+            Qualified name. Consists of namespace and local name.
+        """;
     }
 
     type AxiomItemDefinition {
         extends AxiomBaseDefinition;
 
+        // FIXME: Move this to AxionTypeDefinition -> item(item)
         identifier name {
             space AxiomItemDefinition;
             scope parent;
         }
 
         item type {
             type AxiomTypeReference;
+            documentation """
+                Value type.
+
+                All values must be instances or referenced type or it's subtypes.
+            """;
+            minOccurs 1;
+            maxOccurs 1;
         }
+
         item minOccurs {
             type string;
+            documentation """
+                Declares minimum count of values required for this item.
+            """;
         }
+
         item maxOccurs {
             type string;
+            documentation """
+                Declares maximum possible count of values for this item.
+            """;
         }
-        
+
         item operational {
             type boolean;
-            operational true;
+            documentation """
+                Marks if data are operational (provided by system).
+            """;
         }
-        
+
         item inherited {
             type boolean;
             operational true;
         }
     }
 
-    type AxiomReference {
-        item targetType {
-            type AxiomTypeReference;
-        }
-    }
-
     type AxiomTypeReference {
-        documentation "Type Reference";
+        documentation """
+            Reference to type definition.
+
+            Referenced type definition is referenced by it's fully qualified
+            (namespace and local name).
+        """;
         argument name;
 
         item name {
-            documentation "Name of referenced type";
             type AxiomIdentifier;
+            documentation """
+                Name of referenced type definition.
+                The value must be name of existing type definition, which is 
+                available (visible) to model using this type reference.
+            """;
             minOccurs 1;
             maxOccurs 1;
         }
         item target {
-            documentation "Definition of referenced type";
             type AxiomTypeDefinition;
-            minOccurs 1;
+            documentation """
+                Referenced Type Definition.
+
+                The value is resolved operational definition of referenced type.
+            """;
+            minOccurs 0;
             maxOccurs 1;
             operational true;
         }
@@ -215,8 +291,6 @@ model axiom-lang {
         }
     }
 
-    // "Type library" (temporary)
-
     type SemanticVersion {
         extends string;
     }