Update documentation for random class instance changes

core/src/integration/kotlin/io/github/serpro69/kfaker/docs/Extras.kt

@@ -1,6 +1,7 @@
 package io.github.serpro69.kfaker.docs
 
 import io.github.serpro69.kfaker.Faker
+import io.github.serpro69.kfaker.fakerConfig
 import io.github.serpro69.kfaker.provider.misc.ConstructorFilterStrategy
 import io.github.serpro69.kfaker.provider.misc.FallbackStrategy
 import io.kotest.core.spec.style.DescribeSpec
@@ -161,6 +162,113 @@ class Extras : DescribeSpec({
                 // END extras_random_instance_nine
             }
         }
+
+        context("Configuration levels") {
+            // START extras_random_instance_ten
+            class Foo
+            data class Bar(val int: Int, val uuid: UUID)
+            data class Baz(val foo: Foo, val bar: Bar, val string: String)
+            // END extras_random_instance_ten
+
+            it("should configure random class instance from fakerConfig") {
+                // START extras_random_instance_eleven
+                val cfg = fakerConfig {
+                    randomClassInstance {
+                        typeGenerator<Bar> { Bar(42, UUID.fromString("11111111-1111-1111-1111-111111111111")) }
+                    }
+                }
+                val f = Faker(cfg)
+                val baz: Baz = f.randomProvider.randomClassInstance<Baz>()
+                assertEquals(baz.bar, Bar(42, UUID.fromString("11111111-1111-1111-1111-111111111111")))
+                val anotherBaz = f.randomProvider.new().randomClassInstance<Baz>()
+                assertEquals(anotherBaz.bar, Bar(42, UUID.fromString("11111111-1111-1111-1111-111111111111")))
+                // END extras_random_instance_eleven
+            }
+
+            it("should configure random class instance from randomProvider") {
+                // START extras_random_instance_twelve
+                val cfg = fakerConfig {
+                    randomClassInstance {
+                        typeGenerator<Bar> { Bar(42, UUID.fromString("11111111-1111-1111-1111-111111111111")) }
+                    }
+                }
+                val f = Faker(cfg).also {
+                    it.randomProvider.configure {
+                        typeGenerator<UUID> { UUID.fromString("00000000-0000-0000-0000-000000000000") }
+                    }
+                }
+
+                val bar: Bar = f.randomProvider.randomClassInstance()
+                val baz: Baz = f.randomProvider.randomClassInstance()
+                assertEquals(bar.uuid, UUID.fromString("00000000-0000-0000-0000-000000000000"))
+                assertEquals(baz.bar, Bar(42, UUID.fromString("11111111-1111-1111-1111-111111111111")))
+                // END extras_random_instance_twelve
+            }
+
+            it("should configure random class instance from function") {
+                // START extras_random_instance_thirteen
+                faker.randomProvider.configure {
+                    typeGenerator<Bar> { Bar(42, UUID.fromString("11111111-1111-1111-1111-111111111111")) }
+                }
+                val baz: Baz = faker.randomProvider.randomClassInstance {
+                    typeGenerator<Bar> { Bar(1, UUID.fromString("00000000-0000-0000-0000-000000000000")) }
+                }
+                assertEquals(baz.bar, Bar(1, UUID.fromString("00000000-0000-0000-0000-000000000000")))
+                // END extras_random_instance_thirteen
+            }
+        }
+
+        context("New instances and copies") {
+            class Foo
+            data class Bar(val int: Int, val uuid: UUID)
+            data class Baz(val foo: Foo, val bar: Bar, val string: String)
+
+            it("should create a new instance") {
+                // START extras_random_instance_fourteen
+                val cfg = fakerConfig {
+                    randomClassInstance { // ❶
+                        typeGenerator<Bar> { Bar(1, UUID.fromString("00000000-0000-0000-0000-000000000000")) }
+                    }
+                }
+                val f = Faker(cfg)
+                f.randomProvider.configure { // ❷
+                    typeGenerator<Bar> { Bar(42, UUID.fromString("11111111-1111-1111-1111-111111111111")) }
+                }
+                val new = f.randomProvider.new() // ❸
+                val baz: Baz = f.randomProvider.randomClassInstance<Baz>()
+                val newBaz: Baz = new.randomClassInstance<Baz>()
+                assertEquals(Bar(42, UUID.fromString("11111111-1111-1111-1111-111111111111")), baz.bar)
+                assertEquals(Bar(1, UUID.fromString("00000000-0000-0000-0000-000000000000")), newBaz.bar)
+                // END extras_random_instance_fourteen
+            }
+
+            it("should make a copy") {
+                // START extras_random_instance_fifteen
+                val cfg = fakerConfig { // ❶
+                    randomClassInstance {
+                        typeGenerator<Bar> { Bar(1, UUID.fromString("00000000-0000-0000-0000-000000000000")) }
+                    }
+                }
+                val f = Faker(cfg)
+                f.randomProvider.configure { // ❷
+                    typeGenerator<Bar> { Bar(42, UUID.fromString("11111111-1111-1111-1111-111111111111")) }
+                }
+                val copy = f.randomProvider.copy() // ❸
+                val baz: Baz = f.randomProvider.randomClassInstance<Baz>()
+                val bazCopy: Baz = copy.randomClassInstance<Baz>()
+                assertEquals(Bar(42, UUID.fromString("11111111-1111-1111-1111-111111111111")), baz.bar)
+                assertEquals(Bar(42, UUID.fromString("11111111-1111-1111-1111-111111111111")), bazCopy.bar)
+
+                copy.configure { // ❹
+                    typeGenerator<Bar> { Bar(0, UUID.fromString("22222222-2222-2222-2222-222222222222")) }
+                }
+                val originalBaz: Baz = f.randomProvider.randomClassInstance<Baz>()
+                val reconfiguredBazCopy = copy.randomClassInstance<Baz>()
+                assertEquals(Bar(42, UUID.fromString("11111111-1111-1111-1111-111111111111")), originalBaz.bar)
+                assertEquals(Bar(0, UUID.fromString("22222222-2222-2222-2222-222222222222")), reconfiguredBazCopy.bar)
+                // END extras_random_instance_fifteen
+            }
+        }
     }
 
     describe("Random Everything") {

core/src/integration/kotlin/io/github/serpro69/kfaker/docs/FakerConfiguration.kt

@@ -1,6 +1,7 @@
 package io.github.serpro69.kfaker.docs
 
 import io.github.serpro69.kfaker.Faker
+import io.github.serpro69.kfaker.faker
 import io.github.serpro69.kfaker.fakerConfig
 import io.kotest.core.spec.DisplayName
 import io.kotest.core.spec.style.DescribeSpec
@@ -92,5 +93,25 @@ class FakerConfiguration : DescribeSpec({
                 // END faker_config_five
             }
         }
+
+        context("RandomClassProvider") {
+            it("should configure RandomClassProvider") {
+                // START faker_config_six
+                class Test(
+                    val uuid: UUID,
+                    val name: String,
+                )
+                val config = fakerConfig {
+                    randomClassInstance {
+                        collectionsSize = 6
+                        typeGenerator<UUID> { UUID.fromString("00000000-0000-0000-0000-000000000000") }
+                        namedParameterGenerator("name") { faker {}.name.name() }
+                    }
+                }
+                val test = Faker(config).randomProvider.randomClassInstance<Test>()
+                assertEquals(test.uuid, UUID.fromString("00000000-0000-0000-0000-000000000000"))
+                // END faker_config_six
+            }
+        }
     }
 })

docs/src/orchid/resources/wiki/extras.md

@@ -8,9 +8,11 @@
 ## ToC
 
 * [Random instance of any class](#random-instance-of-any-class)
+  * [Random Class Instance Configuration](#random-class-instance-configuration)
   * [Pre-configuring type generation for constructor arguments](#pre-configuring-type-generation-for-constructor-arguments)
   * [Deterministic constructor selection](#deterministic-constructor-selection)
   * [Configuring the size of generated Collections](#configuring-the-size-of-generated-collections)
+  * [Making a Copy or a New instance of RandomClassProvider](#making-a-new-instance-of-random-class-provider)
 * [Random Everything](#random-everything)
 * [Random Strings from Templates](#random-strings-from-templates)
 
@@ -43,6 +45,80 @@ Random instance generation is available through `Faker().randomProvider`:
 
 <br>
 
+### Random Class Instance Configuration
+
+Random Class Instance configuration can be applied on several levels. Consider the following classes:
+
+{% tabs %}
+
+{% kotlin "Kotlin" %}
+{% filter compileAs('md') %}
+```kotlin
+{% snippet 'extras_random_instance_ten' %}
+```
+{% endfilter %}
+{% endkotlin %}
+
+{% endtabs %}
+
+<br>
+
+#### Configuration via `FakerConfig`
+
+This takes the least precedence and applies to all instances (see [Making a copy/new instance of RandomClassProvider]({{ link(collectionType='wiki', collectionId='', itemId='Extras') }}#making-a-new-instance-of-random-class-provider)) of `RandomClassProvider` if set.
+
+{% tabs %}
+
+{% kotlin "Kotlin" %}
+{% filter compileAs('md') %}
+```kotlin
+{% snippet 'extras_random_instance_eleven' %}
+```
+{% endfilter %}
+{% endkotlin %}
+
+{% endtabs %}
+
+<br>
+
+#### Configuration via `Faker#randomProvider`
+
+This takes higher precedence and will also merge any configuration that was set on the previous level.
+
+{% tabs %}
+
+{% kotlin "Kotlin" %}
+{% filter compileAs('md') %}
+```kotlin
+{% snippet 'extras_random_instance_twelve' %}
+```
+{% endfilter %}
+{% endkotlin %}
+
+{% endtabs %}
+
+<br>
+
+#### Configuration via `randomClassInstance` function
+
+This configuration takes the most precedence and does not take into account configurations applied on other levels.
+
+{% tabs %}
+
+{% kotlin "Kotlin" %}
+{% filter compileAs('md') %}
+```kotlin
+{% snippet 'extras_random_instance_thirteen' %}
+```
+{% endfilter %}
+{% endkotlin %}
+
+{% endtabs %}
+
+{% btc %}{% endbtc %}
+
+<br>
+
 ### Pre-Configuring type generation for constructor arguments
 
 Some, or all, of the constructor params can be instantiated with values following some pre-configured logic using `typeGenerator` or `namedParameterGenerator` functions. Consider the following example:
@@ -96,7 +172,7 @@ val baz: Baz = faker.randomProvider.randomClassInstance {
 class Person(val id: Int, val name: String)
 
 val person: Person = faker.randomProvider.randomClassInstance {
-    typeGenerator<String> { faker.name.fullName() }
+    typeGenerator<String> { faker.name.name() }
 }
 ```
 {% endfilter %}
@@ -248,6 +324,68 @@ At the same time, `typeGenerator` configurator itself can be used with collectio
 
 <br>
 
+### Making a new instance of Random Class Provider
+
+`RandomClassProvider` has two functions: `new` and `copy`, that allow you to create another instance of the class, for example, a one that has a different type generation configuration.
+
+#### New Instance
+
+To make a new instance of `randomProvider`:
+
+{% tabs %}
+
+{% kotlin "Kotlin" %}
+{% filter compileAs('md') %}
+```kotlin
+{% snippet 'extras_random_instance_fourteen' %}
+```
+{% endfilter %}
+{% endkotlin %}
+
+{% endtabs %}
+
+
+<br>
+
+{% info %}
+{% filter compileAs('md') %}
+Any configuration set via `fakerConfig` ( ❶ ), will be applied to the `new` instance ( ❸ ) as well.
+Any configuration set via `faker.randomProvider` instance ( ❷ ) is NOT applied to the `new` instance.
+{% endfilter %}
+{% endinfo %}
+
+<br>
+
+#### Instance Copy
+
+To make a copy of an existing instance of `randomProvider`:
+
+{% tabs %}
+
+{% kotlin "Kotlin" %}
+{% filter compileAs('md') %}
+```kotlin
+{% snippet 'extras_random_instance_fifteen' %}
+```
+{% endfilter %}
+{% endkotlin %}
+
+{% endtabs %}
+
+<br>
+
+{% info %}
+{% filter compileAs('md') %}
+Any configuration that was already applied to `faker.randomProvider` ( ❶ and ❷ ), will be applied to the `copy` ( ❸ ) as well.
+
+The `copy`, just as `new` instance, can of course be reconfigured ( ❹ ) as needed, which does not affect the configuration of the `faker.randomProvider` or configurations of other "copies".
+{% endfilter %}
+{% endinfo %}
+
+{% btc %}{% endbtc %}
+
+<br>
+
 ## Random Everything
 
 Faker provides its wrapper functions around `java.util.Random` (with some additional functionality that is not covered by `java.util.Random`) through `Faker().random` property.

docs/src/orchid/resources/wiki/faker-configuration.md

@@ -8,6 +8,7 @@
 * [Default Configuration](#default-configuration)
 * [Deterministic Random](#deterministic-random)
 * [Locale](#locale)
+* [Random Class Instance](#random-class-instance)
 
 <br>
 
@@ -206,3 +207,16 @@ A list of all locales, and their corresponding dictionary files, can be found on
 {% btc %}{% endbtc %}
 
 <br>
+
+## Random Class Instance
+
+[RandomClassInstance]({{ link(collectionType='wiki', collectionId='', itemId='Extras') }}#random-instance-of-any-class) can also be configured both from the `FakerConfig` level.
+
+{% info %}
+This configuration takes the least precedence and will be overridden by config set on the `faker.randomProvider` level or on the `randomClassInstance` function level.
+See [Random Class Instance Configuration]({{ link(collectionType='wiki', collectionId='', itemId='Extras') }}#random-class-instance-configuration) for more details. 
+{% endinfo %}
+
+{% btc %}{% endbtc %}
+
+<br>