[GitHub] [ignite-3] sashapolo commented on a change in pull request #109: IGNITE-14657 README.md for ignite-configuration module.

[GitBox <gi...@apache.org>]

sashapolo commented on a change in pull request #109:
URL: https://github.com/apache/ignite-3/pull/109#discussion_r623740551



##########
File path: modules/configuration/README.md
##########
@@ -0,0 +1,157 @@
+# Configuration
+
+This module contains the API classes and the implementation for the Ignite configuration framework.
+The idea is to provide the so-called _Unified configuration_ — a common way of configuring both local Ignite nodes
+and remote Ignite clusters. The original concept is described in
+[IEP-55](https://cwiki.apache.org/confluence/display/IGNITE/IEP-55+Unified+Configuration).
+
+## Concepts
+
+### Configuration Schema
+
+Type-safe schema of a configuration, which is used for generating public API interfaces and
+internal implementations to avoid writing boilerplate code. 
+
+All schema classes must end with the `ConfigurationSchema` suffix.
+
+### Configuration Registry
+
+`ConfigurationRegistry` is the entry point of the module.
+
+### Root Key
+
+`RootKey` interface represents a type-safe object that holds the _key_ of the root node. Instances of
+this interface are generated automatically and are mandatory for registering the configuration roots.
+
+### Example Schema
+
+An example configuration schema may look like the following:
+
+```java
+@ConfigurationRoot(rootName = "root", type = ConfigurationType.LOCAL)
+public static class ParentConfigurationSchema {
+    @NamedConfigValue
+    private NamedElementConfigurationSchema elements;
+
+    @ConfigValue
+    private ChildConfigurationSchema child;
+}
+
+@Config
+public static class ChildConfigurationSchema {
+    @Value(hasDefault = true)
+    public String str = "foobar";
+    
+    @Value
+    @Immutable
+    public String str;
+}
+```
+
+* `@ConfigurationRoot` marks the root schema. It contains the following properties:
+  * `type` property, which can either be `LOCAL` or `DISTRIBUTED`. This property dictates the _storage_ type used 
+    to persist the schema — `Vault` or `Metastorage`;
+  * All Ignite configuration instances can be represented by a forest, where every node has a name, usually referred 
+    to as a _key_. The `rootName` property assigns a _key_ to the root node of the tree that will represent 
+    the corresponding configuration schema;
+* `@Config` is similar to the `@ConfigurationRoot` but represents an inner configuration node;
+* `@ConfigValue` marks a nested schema field. Cyclic dependencies are not allowed;
+* `@NamedConfigValue` is similar to `@ConfigValue` but such fields will basically become `Map<String, declared_schema>`;

Review comment:
       > but such fields will basically become `Map<String, declared_schema>`;
   
   This sentence makes little sense

##########
File path: modules/configuration/README.md
##########
@@ -0,0 +1,157 @@
+# Configuration
+
+This module contains the API classes and the implementation for the Ignite configuration framework.
+The idea is to provide the so-called _Unified configuration_ — a common way of configuring both local Ignite nodes
+and remote Ignite clusters. The original concept is described in
+[IEP-55](https://cwiki.apache.org/confluence/display/IGNITE/IEP-55+Unified+Configuration).
+
+## Concepts
+
+### Configuration Schema
+
+Type-safe schema of a configuration, which is used for generating public API interfaces and
+internal implementations to avoid writing boilerplate code. 
+
+All schema classes must end with the `ConfigurationSchema` suffix.
+
+### Configuration Registry
+
+`ConfigurationRegistry` is the entry point of the module.
+
+### Root Key
+
+`RootKey` interface represents a type-safe object that holds the _key_ of the root node. Instances of
+this interface are generated automatically and are mandatory for registering the configuration roots.
+
+### Example Schema
+
+An example configuration schema may look like the following:
+
+```java
+@ConfigurationRoot(rootName = "root", type = ConfigurationType.LOCAL)
+public static class ParentConfigurationSchema {
+    @NamedConfigValue

Review comment:
       Add an explanation about `NamedConfigValue` and `NamedLists`

##########
File path: modules/configuration/README.md
##########
@@ -0,0 +1,157 @@
+# Configuration
+
+This module contains the API classes and the implementation for the Ignite configuration framework.
+The idea is to provide the so-called _Unified configuration_ — a common way of configuring both local Ignite nodes
+and remote Ignite clusters. The original concept is described in
+[IEP-55](https://cwiki.apache.org/confluence/display/IGNITE/IEP-55+Unified+Configuration).
+
+## Concepts
+
+### Configuration Schema
+
+Type-safe schema of a configuration, which is used for generating public API interfaces and
+internal implementations to avoid writing boilerplate code. 
+
+All schema classes must end with the `ConfigurationSchema` suffix.
+
+### Configuration Registry
+
+`ConfigurationRegistry` is the entry point of the module.

Review comment:
       Add more text here

##########
File path: modules/configuration/README.md
##########
@@ -0,0 +1,157 @@
+# Configuration
+
+This module contains the API classes and the implementation for the Ignite configuration framework.
+The idea is to provide the so-called _Unified configuration_ — a common way of configuring both local Ignite nodes
+and remote Ignite clusters. The original concept is described in
+[IEP-55](https://cwiki.apache.org/confluence/display/IGNITE/IEP-55+Unified+Configuration).
+
+## Concepts
+
+### Configuration Schema
+
+Type-safe schema of a configuration, which is used for generating public API interfaces and
+internal implementations to avoid writing boilerplate code. 
+
+All schema classes must end with the `ConfigurationSchema` suffix.
+
+### Configuration Registry
+
+`ConfigurationRegistry` is the entry point of the module.
+
+### Root Key
+
+`RootKey` interface represents a type-safe object that holds the _key_ of the root node. Instances of
+this interface are generated automatically and are mandatory for registering the configuration roots.
+
+### Example Schema
+
+An example configuration schema may look like the following:
+
+```java
+@ConfigurationRoot(rootName = "root", type = ConfigurationType.LOCAL)
+public static class ParentConfigurationSchema {
+    @NamedConfigValue
+    private NamedElementConfigurationSchema elements;
+
+    @ConfigValue
+    private ChildConfigurationSchema child;
+}
+
+@Config
+public static class ChildConfigurationSchema {
+    @Value(hasDefault = true)
+    public String str = "foobar";
+    
+    @Value
+    @Immutable
+    public String str;
+}
+```
+
+* `@ConfigurationRoot` marks the root schema. It contains the following properties:
+  * `type` property, which can either be `LOCAL` or `DISTRIBUTED`. This property dictates the _storage_ type used 
+    to persist the schema — `Vault` or `Metastorage`;

Review comment:
       What is the `Vault` and `Metastorage` and what are the consequences of choosing one?




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org