From 014181ef749d6e298d8adf035817f73b46dd7f43 Mon Sep 17 00:00:00 2001
From: Romain Boisselle <romain@boisselle.dev>
Date: Mon, 28 Dec 2020 08:57:21 +0100
Subject: [PATCH] update documentations

---
 doc/modules/core/pages/install.adoc           | 108 ++++++++-------
 doc/modules/core/pages/using-environment.adoc |  37 ++++-
 doc/modules/extension/pages/configurable.adoc | 126 +++++++++++++++---
 doc/modules/extension/pages/jsr330.adoc       |  22 +--
 4 files changed, 209 insertions(+), 84 deletions(-)

diff --git a/doc/modules/core/pages/install.adoc b/doc/modules/core/pages/install.adoc
index 9ee1ac38..73931096 100644
--- a/doc/modules/core/pages/install.adoc
+++ b/doc/modules/core/pages/install.adoc
@@ -7,36 +7,6 @@
 [[install-jvm]]
 == JVM
 
-=== With Maven
-
-Add the JCenter repository:
-
-[source,xml,subs="attributes"]
-----
-&lt;repositories&gt;
-    &lt;repository&gt;
-      &lt;id&gt;jcenter&lt;/id&gt;
-      &lt;url&gt;https://jcenter.bintray.com&lt;/url&gt;
-    &lt;/repository&gt;
-&lt;/repositories&gt;
-----
-
-Then add the dependency:
-
-[source,xml,subs="attributes"]
-----
-&lt;dependencies&gt;
-    &lt;dependency&gt;
-        &lt;groupId&gt;org.kodein.di&lt;/groupId&gt;
-        &lt;artifactId&gt;kodein-di-jvm&lt;/artifactId&gt;
-        &lt;version&gt;{version}&lt;/version&gt;
-    &lt;/dependency&gt;
-&lt;/dependencies&gt;
-----
-
-WARNING: Use `kodein-di-jvm`, as _Kotlin/Multiplatform_ projects does not work with Maven
-
-
 === With Gradle
 
 Add the JCenter repository:
@@ -59,36 +29,48 @@ dependencies {
 }
 ----
 
-[[kotlin-js]]
-== JavaScript (Gradle)
+[TIP]
+====
+If you are *NOT* using *Gradle 6+*, you should declare the use of the Gradle Metadata experimental feature
 
-Because _Kodein-DI_ for JavaScript is compiled as a https://github.com/umdjs/umd[UMD module], it can be imported:
+[subs="attributes"]
+.settings.gradle.kts
+----
+enableFeaturePreview("GRADLE_METADATA")
+----
 
-* In a browser:
-** as an AMD module (for example with RequireJS) (See index.html in the demo project).
-** Directly in an HTML page with a `<script>` tag (See index2.html in the demo project).
-* In NodeJS, as a regular CJS module.
+Or, import the JVM binaries with `implementation("org.kodein.di:kodein-di-jvm:{version}")`.
+====
+
+=== With Maven
 
 Add the JCenter repository:
 
-[source,groovy,subs="attributes"]
+[source,xml,subs="attributes"]
 ----
-buildscript {
-    repositories {
-        jcenter()
-    }
-}
+&lt;repositories&gt;
+    &lt;repository&gt;
+      &lt;id&gt;jcenter&lt;/id&gt;
+      &lt;url&gt;https://jcenter.bintray.com&lt;/url&gt;
+    &lt;/repository&gt;
+&lt;/repositories&gt;
 ----
 
 Then add the dependency:
 
-[source,groovy,subs="attributes"]
+[source,xml,subs="attributes"]
 ----
-dependencies {
-    compile 'org.kodein.di:kodein-di-js:{version}'
-}
+&lt;dependencies&gt;
+    &lt;dependency&gt;
+        &lt;groupId&gt;org.kodein.di&lt;/groupId&gt;
+        &lt;artifactId&gt;kodein-di-jvm&lt;/artifactId&gt;
+        &lt;version&gt;{version}&lt;/version&gt;
+    &lt;/dependency&gt;
+&lt;/dependencies&gt;
 ----
 
+WARNING: Use `kodein-di-jvm`, as _Kotlin/Multiplatform_ projects does not work with Maven
+
 [[kotlin-multiplatform]]
 == Kotlin/Multiplatform (Gradle)
 
@@ -99,7 +81,7 @@ _Kodein-DI_ uses the new gradle native dependency model.
 
 [TIP]
 ====
-If you are *NOT* using *Gradle 6+*, you should declare the use of the Gralde Metadata experimental feature
+If you are *NOT* using *Gradle 6+*, you must declare the use of the Gralde Metadata experimental feature
 
 [subs="attributes"]
 .settings.gradle.kts
@@ -134,3 +116,33 @@ kotlin {
     }
 }
 ----
+
+[[kotlin-js]]
+== JavaScript (Gradle)
+
+Because _Kodein-DI_ for JavaScript is compiled as a https://github.com/umdjs/umd[UMD module], it can be imported:
+
+* In a browser:
+** as an AMD module (for example with RequireJS) (See index.html in the demo project).
+** Directly in an HTML page with a `<script>` tag (See index2.html in the demo project).
+* In NodeJS, as a regular CJS module.
+
+Add the JCenter repository:
+
+[source,groovy,subs="attributes"]
+----
+buildscript {
+    repositories {
+        jcenter()
+    }
+}
+----
+
+Then add the dependency:
+
+[source,groovy,subs="attributes"]
+----
+dependencies {
+    compile 'org.kodein.di:kodein-di-js:{version}'
+}
+----
\ No newline at end of file
diff --git a/doc/modules/core/pages/using-environment.adoc b/doc/modules/core/pages/using-environment.adoc
index 5ef1155a..dcd835fa 100644
--- a/doc/modules/core/pages/using-environment.adoc
+++ b/doc/modules/core/pages/using-environment.adoc
@@ -174,6 +174,24 @@ class MySpecialRequest(override val di: DI): Request(), DIAware {
 }
 ----
 
+[NOTE]
+====
+You can access the container's bindings within a context translator:
+
+[source, kotlin]
+.Example:
+----
+val di = DI {
+    bind<User>() with scoped(SessionScope).singleton { UserData(session.userId) }
+
+    bind<Translator>() with singleton { RequestTranslator() }
+    registerContextTranslator { r: Request ->
+        instance<Translator>().translate(r)
+     }
+}
+----
+====
+
 
 === Context finder
 
@@ -191,7 +209,24 @@ val di = DI {
 }
 ----
 
-This allows to access a `User` object wihout specifying a context.
+This allows to access a `User` object without specifying a context.
+
+[NOTE]
+====
+You can access the container's bindings within a context finder:
+
+[source, kotlin]
+.Example:
+----
+enum class Env { DEBUG, PRODUCTION }
+class CurrentEnv(var env: Env)
+val di = DI {
+    bind() from scoped(EnvironmentScope).singleton { Service(context) }
+    bind() from singleton { CurrentEnv(Env.PRODUCTION) }
+    registerContextFinder { instance<CurrentEnv>().env }
+}
+----
+====
 
 TIP: Having an other type of context declared will not block from using a context finder.
 
diff --git a/doc/modules/extension/pages/configurable.adoc b/doc/modules/extension/pages/configurable.adoc
index 257f426e..656a2927 100644
--- a/doc/modules/extension/pages/configurable.adoc
+++ b/doc/modules/extension/pages/configurable.adoc
@@ -16,49 +16,135 @@ NOTE: Using or not using this is a matter of taste and is neither recommended no
 
 == Install
 
+[[install-jvm]]
 === JVM
 
-==== With Maven
+==== With Gradle
 
-[source,xml,subs="attributes"]
+[TIP]
+====
+If you are *NOT* using *Gradle 6+*, you should declare the use of the Gradle Metadata experimental feature
+
+[subs="attributes"]
+.settings.gradle.kts
 ----
-&lt;dependency&gt;
-    &lt;groupId&gt;org.kodein.di&lt;/groupId&gt;
-    &lt;artifactId&gt;kodein-di-conf-jvm&lt;/artifactId&gt;
-    &lt;version&gt;{version}&lt;/version&gt;
-&lt;/dependency&gt;
+enableFeaturePreview("GRADLE_METADATA")
 ----
 
-IMPORTANT: Do not remove the `kodein-generic-jvm` (or `kodein-erased-jvm`) dependency.
-           Both dependencies must be declared.
+====
 
-==== With Gradle
+Add the JCenter repository:
 
 [source,groovy,subs="attributes"]
 ----
-compile 'org.kodein.di:kodein-di-conf-jvm:{version}'
+buildscript {
+    repositories {
+        jcenter()
+    }
+}
 ----
 
-IMPORTANT: Do not remove the `kodein-generic-jvm` (or `kodein-erased-jvm`) dependency.
-           Both dependencies must be declared.
+Then add the dependency:
 
+[source,groovy,subs="attributes"]
+----
+dependencies {
+    implementation 'org.kodein.di:kodein-conf-di:{version}'
+}
+----
+
+==== With Maven
+
+Add the JCenter repository:
+
+[source,xml,subs="attributes"]
+----
+&lt;repositories&gt;
+    &lt;repository&gt;
+      &lt;id&gt;jcenter&lt;/id&gt;
+      &lt;url&gt;https://jcenter.bintray.com&lt;/url&gt;
+    &lt;/repository&gt;
+&lt;/repositories&gt;
+----
+
+Then add the dependency:
+
+[source,xml,subs="attributes"]
+----
+&lt;dependencies&gt;
+    &lt;dependency&gt;
+        &lt;groupId&gt;org.kodein.di&lt;/groupId&gt;
+        &lt;artifactId&gt;kodein-di-jvm&lt;/artifactId&gt;
+        &lt;version&gt;{version}&lt;/version&gt;
+    &lt;/dependency&gt;
+&lt;/dependencies&gt;
+----
 
-=== Javascript (Gradle)
+WARNING: Use `kodein-di-conf-jvm`, as _Kotlin/Multiplatform_ projects does not work with Maven
+
+[[kotlin-js]]
+=== JavaScript (Gradle)
+
+Because _Kodein-DI_ for JavaScript is compiled as a https://github.com/umdjs/umd[UMD module], it can be imported:
+
+* In a browser:
+** as an AMD module (for example with RequireJS) (See index.html in the demo project).
+** Directly in an HTML page with a `<script>` tag (See index2.html in the demo project).
+* In NodeJS, as a regular CJS module.
+
+Add the JCenter repository:
+
+[source,groovy,subs="attributes"]
+----
+buildscript {
+    repositories {
+        jcenter()
+    }
+}
+----
+
+Then add the dependency:
 
 [source,groovy,subs="attributes"]
 ----
-compile 'org.kodein.di:kodein-di-conf-js:{version}'
+dependencies {
+    compile 'org.kodein.di:kodein-di-conf-js:{version}'
+}
 ----
 
-IMPORTANT: Do not remove the `kodein-generic-js` (or `kodein-erased-js`) dependency.
-           Both dependencies must be declared.
+[[kotlin-multiplatform]]
+=== Kotlin/Multiplatform (Gradle)
 
+NOTE: _Kodein-DI_ supports the following targets: +
+androidArm32, androidArm64, iosArm32, iosArm64, iosX64, linuxArm32Hfp, linuxMips32, linuxMipsel32, linuxX64, macosX64, mingwX64
 
-=== Native
+_Kodein-DI_ uses the new gradle native dependency model.
 
-- https://dl.bintray.com/kodein-framework/Kodein-DI/native/kodein-di-{version}/kodein-di-conf-{version}.klib[Download kodein-conf-{version}.klib].
-- Add the library to your project.
+Add the JCenter repository:
 
+[source,groovy,subs="attributes"]
+----
+buildscript {
+    repositories {
+        jcenter()
+    }
+}
+----
+
+Then add the dependency:
+
+[source,groovy,subs="attributes"]
+----
+kotlin {
+    sourceSets {
+        commonMain {
+            dependencies {
+                implementation "org.kodein.di:kodein-di-conf:{version}"
+            }
+        }
+    }
+}
+----
 
 == ConfigurableDI
 
diff --git a/doc/modules/extension/pages/jsr330.adoc b/doc/modules/extension/pages/jsr330.adoc
index 117e53e9..cf70de20 100644
--- a/doc/modules/extension/pages/jsr330.adoc
+++ b/doc/modules/extension/pages/jsr330.adoc
@@ -22,6 +22,13 @@ CAUTION: Every-thing that is described here is *a lot less performant* than usin
 [[install]]
 == Install
 
+=== With Gradle
+
+[source,groovy,subs="attributes"]
+----
+implementation("org.kodein.di:kodein-di-jxinject-jvm:{version}")
+----
+
 === With Maven
 
 [source,xml,subs="attributes"]
@@ -33,21 +40,6 @@ CAUTION: Every-thing that is described here is *a lot less performant* than usin
 &lt;/dependency&gt;
 ----
 
-IMPORTANT: Do not remove the "kodein-generic-jvm" (or "kodein-erased-jvm") dependency.
-           Both dependencies must be declared.
-
-
-=== With Gradle
-
-[source,groovy,subs="attributes"]
-----
-compile 'org.kodein.di:kodein-di-jxinject-jvm:{version}'
-----
-
-IMPORTANT: Do not remove the "kodein-generic-jvm" (or "kodein-erased-jvm") dependency.
-           Both dependencies must be declared.
-
-
 [[import-module]]
 === Import the module.