docs: add kdocs

Author: MessiasLima

docs/configuration/index.md

@@ -9,7 +9,7 @@ All configuration is done through `SomeConfig`. Every option has sensible defaul
 
 ```kotlin
 data class SomeConfig(
-    var nullableStrategy: NullableStrategy = NullableStrategy.Random(),
+    var nullableStrategy: NullableStrategy = NullableStrategy.NullOnCircularReference,
     var stringStrategy: StringStrategy = StringStrategy.Random(),
     var collectionStrategy: CollectionStrategy = CollectionStrategy(),
     var seed: Long? = null,
@@ -68,7 +68,7 @@ val stillNeverNull: Person = baseSome()
 
 ### Copying configurations
 
-`SomeConfig.copy()` creates a deep copy, including a fresh copy of the `factories` map. This prevents shared mutable state between config instances:
+`SomeConfig.copy()` creates a new configuration with a fresh copy of the `factories` map. This prevents shared mutable factory registrations between config instances:
 
 ```kotlin
 val base = SomeConfig().apply { stringStrategy = StringStrategy.Uuid }
@@ -79,7 +79,7 @@ val custom = base.copy(seed = 999L)
 
 | Property | Default | Description | Docs                                         |
 |----------|---------|-------------|----------------------------------------------|
-| `nullableStrategy` | `NullableStrategy.Random()` | 50% chance of `null` for nullable types | [NullableStrategy](nullable-strategy.md)     |
+| `nullableStrategy` | `NullableStrategy.NullOnCircularReference` | `null` for nullable circular references | [NullableStrategy](nullable-strategy.md)     |
 | `stringStrategy` | `StringStrategy.Random()` | Random lowercase alphabetic, 8 characters | [StringStrategy](string-strategy.md)         |
 | `collectionStrategy` | `CollectionStrategy()` | Collections of 1 to 5 elements | [CollectionStrategy](collection-strategy.md) |
 | `seed` | `null` | Uses non-deterministic `Random.Default` | —                                            |

docs/configuration/nullable-strategy.md

@@ -2,8 +2,38 @@
 
 Controls whether nullable types produce `null` or a concrete value during fixture generation.
 
+The default is `NullableStrategy.NullOnCircularReference`, which prefers concrete values and only returns `null`
+when a nullable type would otherwise create a circular reference.
+
 ## Variants
 
+### `NullOnCircularReference`
+
+Produces concrete values for nullable types unless resolving the value would create a circular reference.
+
+```kotlin
+some { nullableStrategy = NullableStrategy.NullOnCircularReference }
+```
+
+This is the default strategy.
+
+```kotlin
+data class Node(val next: Node?)
+
+val node = some<Node>()
+
+node.next // null
+```
+
+The nullable circular field is resolved as `null`, so generation stops instead of recursing forever.
+Non-nullable circular references still throw `SomeCircularReferenceException` because no finite value can satisfy them:
+
+```kotlin
+data class StrictNode(val next: StrictNode)
+
+some<StrictNode>() // throws SomeCircularReferenceException
+```
+
 ### `AlwaysNull`
 
 Always produces `null` for nullable types.
@@ -38,10 +68,10 @@ some { nullableStrategy = NullableStrategy.Random(probability = 0.2) }
 // 80% chance of null (mostly null values)
 some { nullableStrategy = NullableStrategy.Random(probability = 0.8) }
 
-// Never generate null (0% chance) — equivalent to NeverNull
+// Never generate null (0% chance) - equivalent to NeverNull
 some { nullableStrategy = NullableStrategy.Random(probability = 0.0) }
 
-// Always generate null (100% chance) — equivalent to AlwaysNull
+// Always generate null (100% chance) - equivalent to AlwaysNull
 some { nullableStrategy = NullableStrategy.Random(probability = 1.0) }
 ```
 
@@ -53,13 +83,14 @@ some { nullableStrategy = NullableStrategy.Random(probability = 1.0) }
 | `0.5` | 50% chance (default) |
 | `1.0` | Always produces `null` (equivalent to `AlwaysNull`) |
 
-The default probability is `0.5`, giving an equal chance of null or non-null values — useful for testing a mix of scenarios.
+The default probability is `0.5`, giving an equal chance of null or non-null values.
 
 ## Summary table
 
 | Strategy | Behavior |
 |----------|----------|
+| `NullOnCircularReference` | Produces concrete nullable values unless a circular reference requires `null` (default) |
 | `AlwaysNull` | Always produces `null` for nullable types |
 | `NeverNull` | Always produces a non-null value |
-| `Random()` | 50% chance of `null` (default) |
-| `Random(probability)` | Custom probability of `null` (0.0–1.0) |
+| `Random()` | 50% chance of `null` |
+| `Random(probability)` | Custom probability of `null` (0.0-1.0) |

src/main/kotlin/dev/appoutlet/some/Some.kt

@@ -6,39 +6,99 @@ import dev.appoutlet.some.core.TypeResolver
 import kotlin.random.Random
 import kotlin.reflect.typeOf
 
+/**
+ * Fixture generator configured with a resolver chain and shared random source.
+ *
+ * Instances are created by [someSetup] and can be reused to generate multiple values with the same configuration.
+ *
+ * @param resolvers Ordered resolver list used to generate values.
+ * @param random Random source shared by resolvers created for this instance.
+ * @param config Configuration used by this generator.
+ */
 class Some(
     val resolvers: List<TypeResolver>,
     val random: Random,
     val config: SomeConfig
 ) {
+    /**
+     * Generates a fixture value of type [T] using this instance's configuration.
+     *
+     * @param T Type to generate.
+     * @return Generated value of type [T].
+     */
     @Suppress("MemberNameEqualsClassName")
     inline fun <reified T> some(): T {
         val session = ResolverChain(resolvers, config.nullableStrategy)
         return session.resolve(typeOf<T>()) as T
     }
 
+    /**
+     * Generates a fixture value of type [T].
+     *
+     * Enables concise usage such as `some<User>()` when `some` is a [Some] instance.
+     *
+     * @param T Type to generate.
+     * @return Generated value of type [T].
+     */
     inline operator fun <reified T> invoke(): T = some()
 
+    /**
+     * Generates a fixture value of type [T] with per-call configuration overrides.
+     *
+     * Overrides are applied to a copy of this instance's configuration and do not mutate the original [Some].
+     *
+     * @param T Type to generate.
+     * @param config Configuration overrides for this call.
+     * @return Generated value of type [T].
+     */
     inline operator fun <reified T> invoke(noinline config: SomeConfig.() -> Unit = {}): T {
         val aggregatedConfig = this.config.copy().apply(config)
         return Some(aggregatedConfig.buildResolvers(random), random, aggregatedConfig).some()
     }
 }
 
+/**
+ * Creates a reusable [Some] generator.
+ *
+ * Use this when multiple fixtures should share the same configuration and random source.
+ *
+ * @param config Configuration applied to the created generator.
+ * @return A configured [Some] instance.
+ */
 fun someSetup(config: SomeConfig.() -> Unit = {}): Some {
     val someConfig = SomeConfig().apply(config)
     val random = someConfig.buildRandom()
     return Some(someConfig.buildResolvers(random), random, someConfig)
 }
 
+/**
+ * Lazily-created default configuration used by top-level [some].
+ */
 val defaultConfig: SomeConfig by lazy { SomeConfig() }
+
+/**
+ * Lazily-created default resolver chain used by top-level [some].
+ */
 val defaultResolvers: List<TypeResolver> by lazy { defaultConfig.buildResolvers() }
 
+/**
+ * Generates a fixture value using the default configuration.
+ *
+ * @param T Type to generate.
+ * @return Generated value of type [T].
+ */
 inline fun <reified T> some(): T {
     val session = ResolverChain(defaultResolvers, defaultConfig.nullableStrategy)
     return session.resolve(typeOf<T>()) as T
 }
 
+/**
+ * Generates a fixture value using one-off configuration overrides.
+ *
+ * @param T Type to generate.
+ * @param config Configuration applied only to this generation call.
+ * @return Generated value of type [T].
+ */
 inline fun <reified T> some(noinline config: SomeConfig.() -> Unit = {}): T {
     val someSetup = someSetup(config)
     return someSetup.some<T>()

src/main/kotlin/dev/appoutlet/some/config/SomeConfig.kt

@@ -41,7 +41,8 @@ import kotlin.reflect.KClass
  * Controls strategies for nullable types, strings, collections, random seeding,
  * and custom factory registrations.
  *
- * @param nullableStrategy Strategy for handling nullable type resolution. Defaults to [NullableStrategy.NullOnCircularReference].
+ * @param nullableStrategy Strategy for handling nullable type resolution.
+ *  Defaults to [NullableStrategy.NullOnCircularReference].
  * @param stringStrategy Strategy for generating string values. Defaults to [StringStrategy.Random].
  * @param collectionStrategy Strategy for generating collection sizes. Defaults to [CollectionStrategy].
  * @param seed Seed for reproducible random generation. If null, uses [Random.Default].

src/main/kotlin/dev/appoutlet/some/core/ResolverChain.kt

@@ -4,17 +4,19 @@ import dev.appoutlet.some.config.NullableStrategy
 import dev.appoutlet.some.exception.SomeCircularReferenceException
 import dev.appoutlet.some.exception.SomeUnresolvableTypeException
 import kotlin.reflect.KType
-import kotlin.reflect.full.createType
 
 /**
  * Resolution session that manages the type resolution chain and tracks circular dependencies.
  *
  * This class maintains a mutable stack of types currently being resolved to detect circular references.
  * Each call to `some()` creates a new instance of this session to ensure thread safety.
+ *
+ * @param resolvers Ordered resolver list. The first resolver that supports a type is used.
+ * @param nullableStrategy Strategy used when a circular reference is detected for a nullable type.
  */
 class ResolverChain(
     val resolvers: List<TypeResolver>,
-    private val nullableStrategy: NullableStrategy = NullableStrategy.NullOnCircularReference
+    private val nullableStrategy: NullableStrategy = NullableStrategy.NullOnCircularReference,
 ) {
     private val resolutionStack = mutableListOf<KType>()
 
@@ -25,6 +27,18 @@ class ResolverChain(
     val stack: List<KType>
         get() = resolutionStack.toList()
 
+    /**
+     * Resolves a value for [type] using the first matching resolver.
+     *
+     * The type is added to the resolution stack while it is being resolved and removed even if resolution fails.
+     * If the type would create a circular reference, [handleCircularReference] decides whether to return `null`
+     * or throw based on the configured [NullableStrategy].
+     *
+     * @param type Type to resolve.
+     * @return A generated value for [type], or `null` when nullable circular references are allowed.
+     * @throws SomeCircularReferenceException when a circular reference cannot be represented as `null`.
+     * @throws SomeUnresolvableTypeException when no resolver supports [type].
+     */
     fun resolve(type: KType): Any? {
         if (detectCircularReference(type)) {
             return handleCircularReference(type)
@@ -45,6 +59,14 @@ class ResolverChain(
         }
     }
 
+    /**
+     * Returns whether [type] would repeat a classifier already on the resolution stack.
+     *
+     * Classifier comparison treats `T` and `T?` as the same logical type, which is required to detect recursive
+     * fields such as `data class Node(val next: Node?)`. The non-nullable case immediately after a nullable stack
+     * entry is not circular: that is the expected path where [dev.appoutlet.some.resolver.NullableResolver]
+     * unwraps `T?` into `T` before resolving the concrete value.
+     */
     private fun detectCircularReference(type: KType): Boolean {
         val sameClassifierDetected = resolutionStack.any { it.classifier == type.classifier }
 
@@ -56,9 +78,19 @@ class ResolverChain(
         }
     }
 
+    /**
+     * Handles a circular reference that was detected for [type].
+     *
+     * Nullable circular references can be represented as `null` when the configured strategy allows it. Non-nullable
+     * circular references always throw because there is no finite value that satisfies the type.
+     *
+     * @param type Type that would create a circular reference.
+     * @return `null` when [type] is nullable and the nullable strategy allows null for circular references.
+     * @throws SomeCircularReferenceException when the circular reference cannot be resolved as `null`.
+     */
     private fun handleCircularReference(type: KType): Nothing? {
-        val strategyAllowsNull =  nullableStrategy is NullableStrategy.AlwaysNull ||
-                nullableStrategy is NullableStrategy.NullOnCircularReference
+        val strategyAllowsNull = nullableStrategy is NullableStrategy.AlwaysNull ||
+            nullableStrategy is NullableStrategy.NullOnCircularReference
 
         if (type.isMarkedNullable && strategyAllowsNull) {
             return null

src/main/kotlin/dev/appoutlet/some/resolver/NullableResolver.kt

@@ -12,15 +12,27 @@ import kotlin.reflect.full.createType
  *
  * - **NullOnCircularReference** – delegates to the chain to resolve normally (might be null if a cycle is detected).
  * - **AlwaysNull** – always returns `null`.
- * - **NeverNull** – always resolves a non‑null value.
+ * - **NeverNull** – always resolves a non-null value.
  * - **Random** – returns `null` based on the strategy's probability.
+ *
+ * @param nullableStrategy Strategy used to decide whether nullable types should resolve to `null`.
+ * @param random Random source used by [NullableStrategy.Random].
  */
 class NullableResolver(
     private val nullableStrategy: NullableStrategy = NullableStrategy.NullOnCircularReference,
     private val random: Random
 ) : TypeResolver {
     override fun canResolve(type: KType): Boolean = type.isMarkedNullable
 
+    /**
+     * Resolves [type] according to [nullableStrategy].
+     *
+     * Strategies that choose a concrete value resolve the non-null version of [type] through [chain].
+     *
+     * @param type Nullable type to resolve.
+     * @param chain Resolver chain used to create non-null values when needed.
+     * @return `null` or a generated non-null value for [type].
+     */
     override fun resolve(type: KType, chain: ResolverChain): Any? {
         return when (nullableStrategy) {
             is NullableStrategy.NullOnCircularReference -> createNonNullInstance(type, chain)
@@ -37,6 +49,12 @@ class NullableResolver(
         }
     }
 
+    /**
+     * Resolves the non-null version of [type] through [chain].
+     *
+     * Circular references are still detected by [ResolverChain], which decides whether the current strategy allows
+     * the circular value to be represented as `null`.
+     */
     private fun createNonNullInstance(
         type: KType,
         chain: ResolverChain
@@ -45,6 +63,9 @@ class NullableResolver(
         return chain.resolve(nonNullType)
     }
 
+    /**
+     * Creates a copy of [type] with the nullable marker removed.
+     */
     private fun createNonNullType(type: KType): KType {
         return type.classifier?.createType(type.arguments, false) ?: type
     }

src/test/kotlin/dev/appoutlet/some/integration/CircularReferenceIntegrationTest.kt

@@ -20,6 +20,49 @@ class CircularReferenceIntegrationTest {
         assertNull(node.next)
     }
 
+    @Test
+    fun `nullable top-level circular type returns instance with null circular field by default`() {
+        val node: Node? = some<Node?>()
+
+        val result = assertIs<Node>(node)
+        assertNull(result.next)
+    }
+
+    @Test
+    fun `nullable top-level circular type returns instance with null circular field under NullOnCircularReference`() {
+        val node: Node? = some<Node?> {
+            nullableStrategy = NullableStrategy.NullOnCircularReference
+        }
+
+        val result = assertIs<Node>(node)
+        assertNull(result.next)
+    }
+
+    @Test
+    fun `nullable top-level circular type throws under NeverNull strategy`() {
+        assertFailsWith<SomeCircularReferenceException> {
+            some<Node?> {
+                nullableStrategy = NullableStrategy.NeverNull
+            }
+        }
+    }
+
+    @Test
+    fun `nullable top-level indirect circular type returns instance with null circular field by default`() {
+        val a: IndirectA? = some<IndirectA?>()
+
+        val result = assertIs<IndirectA>(a)
+        val b = assertIs<IndirectB>(result.b)
+        assertNull(b.a)
+    }
+
+    @Test
+    fun `nullable top-level strict circular type still throws by default`() {
+        assertFailsWith<SomeCircularReferenceException> {
+            some<StrictNode?>()
+        }
+    }
+
     @Test
     fun `circular non-nullable field still throws SomeCircularReferenceException`() {
         assertFailsWith<SomeCircularReferenceException> {