Add docs and unit tests for the new() parameterized function

Author: romainbsl

doc/modules/core/pages/bindings.adoc

@@ -392,6 +392,26 @@ val di = DI {
 <1> Binding of `Dice`. It gets its transitive dependencies.
 
 Those tricks are limited to 0 to 10 constructor parameters.
+
+==== Mixing manual and auto-resolved constructor arguments
+
+You can also specify some constructor arguments manually while letting Kodein-DI auto-resolve the others:
+
+[source, kotlin]
+.Example: mixing manual and auto-resolved arguments
+----
+class GameEngine(val dice: Dice, val maxPlayers: Int, val gameName: String)
+
+val di = DI {
+    bindSingleton<Dice> { RandomDice(6) }
+    bindSingleton<GameEngine> {
+        new(::GameEngine, a2 = 4, a3 = "Rolling Dice") // <1>
+    }
+}
+----
+<1> The `dice` parameter is auto-resolved from the container, while `maxPlayers` and `gameName` are provided manually.
+
+You can specify any combination of arguments using their position (`a1`, `a2`, `a3`, etc.), and all non-specified arguments will be automatically retrieved from the DI container.
 ====
 
 The binding functions are in the same environment as the `newInstance` function described in the <<injection, dependency injection section>>.

doc/modules/core/pages/injection-retrieval.adoc

@@ -116,7 +116,46 @@ val di = DI {
 
 This function is available for classes with up to 22 constructor parameters.
 
-This function also supports using arguments, such as those in `bindFactory` or `bindMultiton` functions.
+==== Mixing manual and auto-resolved arguments
+
+You can also provide specific constructor arguments manually while letting the rest be auto-resolved from the DI container.
+This is useful when you need to pass configuration values or runtime parameters:
+
+[source,kotlin]
+----
+class GameEngine(val dice: Dice, val maxPlayers: Int, val gameName: String)
+
+val di = DI {
+    bind<Dice> { singleton { RandomDice(6) } }
+    bind<GameEngine> {
+        singleton {
+            new(::GameEngine, a2 = 4, a3 = "Poker") // <1>
+        }
+    }
+}
+----
+<1> The `dice` parameter (position 1) is auto-resolved, while `maxPlayers` (position 2) and `gameName` (position 3) are provided manually.
+
+You can specify any combination of arguments using their position (`a1`, `a2`, `a3`, etc.):
+
+[source,kotlin]
+----
+class Config(val host: String, val port: Int, val db: Database, val timeout: Int)
+
+val di = DI {
+    bindSingleton<Database> { PostgresDB() }
+    bindSingleton<Config> {
+        new(::Config, a1 = "localhost", a2 = 8080, a4 = 30) // <1>
+    }
+}
+----
+<1> Parameters 1, 2, and 4 are provided manually, while parameter 3 (`db`) is auto-resolved from the container.
+
+NOTE: All non-specified arguments will be automatically retrieved from the DI container using `instance()`.
+
+==== Using factory/multiton arguments with `new`
+
+This function also supports using arguments from `bindFactory` or `bindMultiton` functions.
 For them, provide your argument type in the lambda parameter (that way you don't need to specify type arguments),
 and then pass it as the first parameter to the `new` function:
 

kodein-di/src/commonTest/kotlin/org/kodein/di/Tests_26_New.kt

@@ -75,4 +75,117 @@ internal class Tests_26_New {
 
         assertNotSame(a, b.a)
     }
+    
+    class C(val a: A, val x: Int, val y: String)
+
+    @Test
+    fun test_04_new_with_named_args_all_manual() {
+        val di = DI {
+            bindSingleton { new(::A) }
+            bindSingleton { new(::C, a1 = A(), a2 = 42, a3 = "test") }
+        }
+
+        val c: C by di.instance()
+        val a: A by di.instance()
+
+        assertNotSame(a, c.a)
+        kotlin.test.assertEquals(42, c.x)
+        kotlin.test.assertEquals("test", c.y)
+    }
+
+    @Test
+    fun test_05_new_with_named_args_partial() {
+        val di = DI {
+            bindSingleton { new(::A) }
+            bindSingleton { new(::C, a2 = 99, a3 = "partial") }
+        }
+
+        val c: C by di.instance()
+        val a: A by di.instance()
+
+        assertSame(a, c.a)
+        kotlin.test.assertEquals(99, c.x)
+        kotlin.test.assertEquals("partial", c.y)
+    }
+
+    @Test
+    fun test_06_new_with_named_args_skip_middle() {
+        val di = DI {
+            bindSingleton { new(::A) }
+            bindSingleton { new(::C, a1 = A(), a3 = "skip") }
+        }
+
+       
+        kotlin.test.assertFailsWith<DI.NotFoundException> {
+            val c: C by di.instance()
+            c.x
+        }
+    }
+
+    class D(val x: Int, val y: Int, val z: Int, val w: Int)
+
+    @Test
+    fun test_07_new_with_multiple_named_args() {
+        val di = DI {
+            bindSingleton { new(::D, a1 = 1, a2 = 2, a3 = 3, a4 = 4) }
+        }
+
+        val d: D by di.instance()
+        kotlin.test.assertEquals(1, d.x)
+        kotlin.test.assertEquals(2, d.y)
+        kotlin.test.assertEquals(3, d.z)
+        kotlin.test.assertEquals(4, d.w)
+    }
+
+    @Test
+    fun test_08_new_with_named_args_and_bindings() {
+        val di = DI {
+            bindConstant("x") { 100 }
+            bindConstant("y") { 200 }
+            bindConstant("z") { 300 }
+            bindConstant("w") { 400 }
+            bindSingleton { new(::D, a2 = 222, a4 = 444) }
+        }
+
+       
+        kotlin.test.assertFailsWith<DI.NotFoundException> {
+            val d: D by di.instance()
+            d.x
+        }
+    }
+
+    class E(val a: A, val b: B)
+
+    @Test
+    fun test_09_new_with_mixed_dependencies() {
+        val di = DI {
+            bind { singleton { new(::A) } }
+            bind { singleton { new(::B) } }
+            bind { singleton { new(::E, a2 = B(A())) } }
+        }
+
+        val e: E by di.instance()
+        val a: A by di.instance()
+        val b: B by di.instance()
+
+        assertSame(a, e.a)
+        assertNotSame(b, e.b)
+    }
+
+    @Test
+    fun test_10_new_with_provider_and_named_args() {
+        val di = DI {
+            bindSingleton { new(::A) }
+            bindProvider { new(::C, a2 = 10, a3 = "provider") }
+        }
+
+        val c1: C by di.instance()
+        val c2: C by di.instance()
+
+        assertNotSame(c1, c2)
+        kotlin.test.assertEquals(10, c1.x)
+        kotlin.test.assertEquals(10, c2.x)
+        kotlin.test.assertEquals("provider", c1.y)
+        kotlin.test.assertEquals("provider", c2.y)
+    }
 }