Skip to content

Commit

Permalink
improve documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
Romain Boisselle committed May 25, 2020
1 parent 47dbaa1 commit acc0660
Show file tree
Hide file tree
Showing 2 changed files with 64 additions and 49 deletions.
21 changes: 8 additions & 13 deletions doc/core.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,14 @@ _Kodein-DI_ is compatible with all platforms that the Kotlin language compiles t
Since `7.0.0`, a new https://github.com/Kodein-Framework/Kodein-Type[type system] has been designed and included to _Kodein-DI_.
Thus, it appears to the developer that there is no more _obvious_ differences between platforms, you no longer have to choose between `erased` or `generic` dependencies.
Starting from `7.0.0`, _Kodein-DI_ is using the `generic` version of the type system, meaning you should be able to bind generics easily for _Kotlin/Multiplatform_ projects.
So, whatever platform you are targeting, `bind<List<String>>()` and `bind<List<Int>>()` will represent two different bindings. +
Similarly, `di.instance<List<String>>()` and `di.instance<List<Int>>()` will yield two different list.

[INFO]
====
Since *7.0*, _Kodein-DI_ can use `generic` for non JVM platforms, thus it is now the default implementation.
However you still can force the use of `erased` with the generic and erased function forms!
====

=== The JVM case

Expand Down Expand Up @@ -2021,19 +2029,6 @@ Note that if no argument is provided, the argument to the lambda will be `Unit`.
[[erased-version]]
== Erased version pitfalls

=== The type erasure problem

When using the `generic` version on the JVM, _Kodein-DI_ is immune to type erasure, meaning that `bind<List<String>>()` and `bind<List<Int>>()` will represent two different bindings. +
Similarly, `di.instance<List<String>>()` and `di.instance<List<Int>>()` will yield two different list.

Even if generics are now available for every platforms (targeted by Kotlin compiler), the JVM version relies heavily on the a specific implementation, which is known to be slow.

To improve performance, you can use the `erased` function from _Kodein-DI_, which is faster, but do suffer from type erasure!

Since *7.0*, _Kodein-DI_ can use `generic` for non JVM platforms, thus it is now the default implementation.
However you still can force the use of `erased` with the generic and erased function forms!


=== Using generic and erased function forms

Each DI function that handles a type exists in two form: as inline (lowercased first letter) and as regular function (uppercased first letter). +
Expand Down
92 changes: 56 additions & 36 deletions doc/migration-6to7.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@ It gives us the ability to handle generic types for all the platforms, including
for the JVM, the mechanism remains the same as before, by using reflection.

We still have both implementations with `generic` and `erased` types, but by default, *Kodein-DI* is using the `generic` version.
This means that *Native* and *JS* targets are now compatible with generics, meaning that `bind<List<String>>()` and `bind<List<Int>>()` will represent two different bindings.

TIP: Checkout the link:core.adoc[full documentation] for more details.

Expand Down Expand Up @@ -119,36 +120,39 @@ but sometimes you may have to do this manually. Here is a bunch of use cases tha
==== Kodein interface

When migrating to *Kodein-DI 7+*, you will quickly notice some compile / deprecation errors.
The first one might be on the `Kodein` interface.

Sometimes, IDEA will encourage you to refactor your code with some actions:
The first one might be on the more import type in _Kodein-DI_, `Kodein`.

.With Alt+Enter / Cmd+Enter
image::https://raw.githubusercontent.com/Kodein-Framework/Kodein-DI/{branch}/doc/res/6to7/kodein-to-di.png[Kodein to DI]
.In the import section (Alt+Enter / Cmd+Enter)
image::https://raw.githubusercontent.com/Kodein-Framework/Kodein-DI/{branch}/doc/res/6to7/kodein-to-di-2.png[Kodein to DI]
Sometimes, _IntelliJ IDEA_ will encourage you to refactor your code with some actions, with _Alt+Enter_ / _Cmd+Enter_.

Sometimes it won't resolve the problem, but will still have some action to replace the deprecated interface...

.With Alt+Enter / Cmd+Enter
image::https://raw.githubusercontent.com/Kodein-Framework/Kodein-DI/{branch}/doc/res/6to7/kodein-builder.png[Kodein-DI builder]
[cols="65%,<.^35%a",grid="none",frame="none"]
|===
|image:https://raw.githubusercontent.com/Kodein-Framework/Kodein-DI/{branch}/doc/res/6to7/kodein-to-di.png[Kodein to DI, 800]
|Either from your code
|image:https://raw.githubusercontent.com/Kodein-Framework/Kodein-DI/{branch}/doc/res/6to7/kodein-to-di-2.png[Kodein to DI, 800]
|Or in the import section
|image:https://raw.githubusercontent.com/Kodein-Framework/Kodein-DI/{branch}/doc/res/6to7/kodein-builder.png[Kodein-DI builder, 500]
|Sometimes it won't resolve the deprecation annotations, but will still have some actions to replace the deprecated interface...
|===

==== KodeinAware interface

The second most important type in Kodein-DI is `KodeinAware`, that we will need to refactor to ... `DIAware`.
The second most important type in _Kodein-DI_ is `KodeinAware`, that we will need to refactor to ... `DIAware`.

If you were using `KodeinAware` in your projects, you might end up with something like this:

.Both interface implementation and the class implementing it are with errors.
image::https://raw.githubusercontent.com/Kodein-Framework/Kodein-DI/{branch}/doc/res/6to7/diaware-1.png[DIAware]
[cols="65%,<.^35%a",grid="none",frame="none"]
|===
|image:https://raw.githubusercontent.com/Kodein-Framework/Kodein-DI/{branch}/doc/res/6to7/diaware-1.png[DIAware, 800]
|Both interface implementation and the class implementing it are with errors.
|===

First thing, replace `KodeinAware` with `DIAware`:
First thing, replace `KodeinAware` with `DIAware` (_Alt+Enter_ / _Cmd+Enter_ is your best friend here):

.With Alt+Enter / Cmd+Enter
image::https://raw.githubusercontent.com/Kodein-Framework/Kodein-DI/{branch}/doc/res/6to7/diaware-2.png[DIAware]
image:https://raw.githubusercontent.com/Kodein-Framework/Kodein-DI/{branch}/doc/res/6to7/diaware-2.png[DIAware, 800]

After that, you will need to make changes to the class that is implementing `DIAware`.
We also had renamed the properties from KodeinAware`.
After that, you will need to make changes to the class that is implementing `DIAware`. +
Because we also had renamed the properties from `KodeinAware`, you might have some errors on the following properties.

[options="header",width="50%"]
|=======
Expand All @@ -158,39 +162,50 @@ We also had renamed the properties from KodeinAware`.
| `kodeinTrigger` | `diTrigger`
|=======

.Unfortunately, IDEA won't help you for migrating those properties, you will have to do it manually
image::https://raw.githubusercontent.com/Kodein-Framework/Kodein-DI/{branch}/doc/res/6to7/diaware-3.png[DIAware]
image:https://raw.githubusercontent.com/Kodein-Framework/Kodein-DI/{branch}/doc/res/6to7/diaware-3.png[DIAware, 800]

Unfortunately, _IntelliJ IDEA_ won't help you for migrating those properties, you will have to do it manually. +

So, you need to replace `override kodein: Kodein` by `override di: DI`, either in the constructor or in the member implementation.
image::https://raw.githubusercontent.com/Kodein-Framework/Kodein-DI/{branch}/doc/res/6to7/diaware-4.png[DIAware]
[cols="65%,<.^35%a",grid="none",frame="none"]
|===
|image:https://raw.githubusercontent.com/Kodein-Framework/Kodein-DI/{branch}/doc/res/6to7/diaware-4.png[DIAware, 800]
|Replace `override kodein: Kodein` by `override di: DI`, either in the constructor or in the member implementation.
|image:https://raw.githubusercontent.com/Kodein-Framework/Kodein-DI/{branch}/doc/res/6to7/diaware-5.png[DIAware, 800]
|Here we are, nice and fresh!
|===

.Finally, no more errors!
image::https://raw.githubusercontent.com/Kodein-Framework/Kodein-DI/{branch}/doc/res/6to7/diaware-5.png[DIAware]
The same manipulation goes for `kodeinContext` and `kodeinTrigger`

.The same manipulation goes for `kodeinContext` and `kodeinTrigger`
image::https://raw.githubusercontent.com/Kodein-Framework/Kodein-DI/{branch}/doc/res/6to7/kcontext.png[kcontext]
image:https://raw.githubusercontent.com/Kodein-Framework/Kodein-DI/{branch}/doc/res/6to7/kcontext.png[kcontext, 800]

[IMPORTANT]
====
.In the cases of `kodeinContext`, the property AND the expression might worth changing
image::https://raw.githubusercontent.com/Kodein-Framework/Kodein-DI/{branch}/doc/res/6to7/dicontext.png[dicontext]
In the cases of `kodeinContext`, the property AND the expression might worth changing
image:https://raw.githubusercontent.com/Kodein-Framework/Kodein-DI/{branch}/doc/res/6to7/dicontext.png[dicontext]
====

==== Binding & retrieval

Binding and retrieval are really easier as they just have been deprecated and moved to `org.kodein.di`.

.No error here ;)
image::https://raw.githubusercontent.com/Kodein-Framework/Kodein-DI/{branch}/doc/res/6to7/binder-1.png[Builder]
.Deprecation message suggest to use the functions defined in `org.kodein.di`.
image::https://raw.githubusercontent.com/Kodein-Framework/Kodein-DI/{branch}/doc/res/6to7/binder-2.png[Builder]
.Once again IDEA won't help you there, just drop the imports `org.kodein.di.erased` / `org.kodein.di.generic`
image::https://raw.githubusercontent.com/Kodein-Framework/Kodein-DI/{branch}/doc/res/6to7/binder-3.png[Builder]

[cols="65%,<.^35%a",grid="none",frame="none"]
|===
|image:https://raw.githubusercontent.com/Kodein-Framework/Kodein-DI/{branch}/doc/res/6to7/binder-1.png[Builder]
|No error here ;)
|image:https://raw.githubusercontent.com/Kodein-Framework/Kodein-DI/{branch}/doc/res/6to7/binder-2.png[Builder]
|Deprecation message suggest to use the functions defined in `org.kodein.di`.
|image:https://raw.githubusercontent.com/Kodein-Framework/Kodein-DI/{branch}/doc/res/6to7/binder-3.png[Builder]
|Once again _IntelliJ IDEA_ won't help you there, just drop the imports `org.kodein.di.erased` / `org.kodein.di.generic`
|===

IMPORTANT: Removing the package imports `org.kodein.di.erased` / `org.kodein.di.generic` should help you in lot of cases.

.Otherwise, just re-import the right package!
image::https://raw.githubusercontent.com/Kodein-Framework/Kodein-DI/{branch}/doc/res/6to7/binder-4.png[Builder]
Otherwise, just re-import the right package!

image:https://raw.githubusercontent.com/Kodein-Framework/Kodein-DI/{branch}/doc/res/6to7/binder-4.png[Builder]

==== All the matches

As said before, all the classes / objects named after *Kodein* have been renamed with *DI*.
Here is the table of all the correspondences, for the public classes:
Expand Down Expand Up @@ -225,6 +240,11 @@ Here is the table of all the correspondences, for the public classes:

== What about your favorite framework?

Each one of the framework modules relies heavily on the core library of _Kodein-DI_, `kodein-di`.
So, there is not so much migration here, mostly extensions functions to access easily to the DI container.

You will find the table of correspondence for each framework right below.

=== Android

Importing the *Android* modules of *Kodein-DI* are now easier. You don't need to chose between `erased` and `generic` anymore.
Expand Down

0 comments on commit acc0660

Please sign in to comment.