From e4138b2cce80b9ed96ad79abfb22d6bef9aa450e Mon Sep 17 00:00:00 2001
From: soywiz <soywiz@gmail.com>
Date: Mon, 3 Jul 2023 19:58:37 +0200
Subject: [PATCH] Explain how to use Korinject basic API

---
 docs/korinject/index.md | 66 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)

diff --git a/docs/korinject/index.md b/docs/korinject/index.md
index 1ea5db92f7..4a4661ab73 100644
--- a/docs/korinject/index.md
+++ b/docs/korinject/index.md
@@ -13,6 +13,72 @@ Portable Kotlin Common library to do asynchronous dependency injection.
 
 {% include toc_include.md %}
 
+## Creating a new injector
+
+An injector allow to hold instances, singletons and class constructions, so it allows to access instances later.
+
+```kotlin
+val injector = AsyncInjector()
+```
+
+### Creating a child injector
+
+A child injector, will be able to access/create instances created by parent and ancestor injectors,
+but all the new mappings will be limited to the child injector.
+
+```kotlin
+val injector = injector.child()
+```
+
+## Mappings
+
+Before getting or constructing instances, it is mandatory to map some instances, singletons or prototypes.
+
+### Instances
+
+If you want to save an already constructed instance for later usage, you can map an instance like this:
+
+```kotlin
+injector.mapInstance(myInstance)
+// or
+injector.mapInstance<MyInstanceClass>(myInstance)
+```
+
+Instances are useful for configurations.
+
+### Singletons
+
+If you want to construct a singleton, in a way that all its dependencies are resolved automatically, you can use a singleton.
+A singleton will create a single instance per injector once, lazily when first requested.
+
+```kotlin
+injector.mapSingleton<MyClass> { MyClass(get(), get(), get(), ...) }
+```
+
+Depending on the number of constructor parameters, it is needed to provide the exact number of `get()`.
+Singletons are useful for services.
+
+### Prototypes
+
+If you want to construct a new object every time a specific type instance is requested, you can map prototypes.
+Similarly to singletons:
+
+```kotlin
+injector.mapPrototype<MyClass> { MyClass(get(), get(), get(), ...) }
+```
+
+## Getting instances
+
+Once the injector has been configured, you can start to request instances.
+If the requested class was mapped as an instance, the provided instance will be returned,
+if the requested class was mapped as a singleton, a new instance will be created once, cached, and returned every time.
+And if the requested class was mapped as a prototype, a new class will be constructed and returned every time.
+
+```kotlin
+val instanceOrThrow: MyClass = injector.get<MyClass>()
+val nullable: MyClass? = injector.getOrNull<MyClass>()
+```
+
 ## API
 
 ```kotlin