Add javadoc documentation (#52)

Author: mattmook

README.adoc

@@ -92,6 +92,8 @@ The sequence can hang indefinitely if the applied operators prevent the generati
 
 Everything can be customised, see link:fixture/configuration-options.adoc[configuration options] for more details.
 
+link:fixture/advanced-customisation.adoc[Advanced engine customisation] is also possible if the above options are not enough.
+
 == Kotest integration: property based testing
 
 The library provides {link-appmattus} powered property based testing for https://github.com/kotest/kotest/[Kotest].
@@ -106,7 +108,7 @@ See link:fixture-javafaker/README.adoc[Java Faker integration] for more details.
 
 == Generex integration: regex to random string
 
-To generate a random string from a Regex, look no further than the Generex integration.
+To generate a random string from a regular expression, look no further than the Generex integration.
 
 See link:fixture-generex/README.adoc[Generex integration] for more details.
 

fixture-generex/src/main/kotlin/com/appmattus/kotlinfixture/config/GeneratorString.kt

@@ -18,12 +18,52 @@ package com.appmattus.kotlinfixture.config
 
 import com.mifmif.common.regex.Generex
 
+/**
+ * # Generate a random string from a regular expression
+ *
+ * ```
+ * data class DataClass(val index: String, val value: String)
+ *
+ * val indexRegex = "[a-z][0-9]".toRegex()
+ * val valueRegex = "[A-Z]{3}".toRegex()
+ *
+ * val fixture = kotlinFixture {
+ *     factory<String> { regexToRandom(indexRegex) }
+ *
+ *     property(DataClass::value) { regexToRandom(valueRegex) }
+ * }
+ *
+ * println(fixture<DataClass>()) // DataClass(index=m3, value=CGJ)
+ * ```
+ *
+ * IMPORTANT: Be careful with object creation inside the generation function as it will be called for every instance of the object you create.
+ */
 fun Generator<String>.regexToRandom(regex: String, minLength: Int = 1, maxLength: Int = Int.MAX_VALUE): String {
     return Generex(regex).apply {
         setSeed(random.nextLong())
     }.random(minLength, maxLength)
 }
 
+/**
+ * # Generate a random string from a regular expression
+ *
+ * ```
+ * data class DataClass(val index: String, val value: String)
+ *
+ * val indexRegex = "[a-z][0-9]".toRegex()
+ * val valueRegex = "[A-Z]{3}".toRegex()
+ *
+ * val fixture = kotlinFixture {
+ *     factory<String> { regexToRandom(indexRegex) }
+ *
+ *     property(DataClass::value) { regexToRandom(valueRegex) }
+ * }
+ *
+ * println(fixture<DataClass>()) // DataClass(index=m3, value=CGJ)
+ * ```
+ *
+ * IMPORTANT: Be careful with object creation inside the generation function as it will be called for every instance of the object you create.
+ */
 fun Generator<String>.regexToRandom(regex: Regex, minLength: Int = 1, maxLength: Int = Int.MAX_VALUE): String {
     return regexToRandom(regex.pattern, minLength, maxLength)
 }

fixture-javafaker/src/main/kotlin/com/appmattus/kotlinfixture/decorator/fake/javafaker/JavaFakerConfiguration.kt

@@ -29,16 +29,19 @@ import java.time.ZoneId
 import java.time.temporal.ChronoUnit
 import java.util.Locale
 
-data class JavaFakerConfiguration(
-    val creditCard: CreditCard = CreditCard.Any,
-    val ipAddress: IpAddress = IpAddress.V4,
-    val isbn10Separator: Boolean = false,
-    val isbn13Separator: Boolean = false,
-    val locale: Locale = Locale.ENGLISH,
-    val password: Password = Password(),
-    val temperature: Temperature = Temperature.Celsius,
-    val userAgent: UserAgent = UserAgent.Any,
-    val properties: Map<String, Faker.(JavaFakerConfiguration) -> Any?> = defaultMap
+/**
+ * Configuration for the [JavaFakerStrategy]
+ */
+data class JavaFakerConfiguration internal constructor(
+    internal val creditCard: CreditCard = CreditCard.Any,
+    internal val ipAddress: IpAddress = IpAddress.V4,
+    internal val isbn10Separator: Boolean = false,
+    internal val isbn13Separator: Boolean = false,
+    internal val locale: Locale = Locale.ENGLISH,
+    internal val password: Password = Password(),
+    internal val temperature: Temperature = Temperature.Celsius,
+    internal val userAgent: UserAgent = UserAgent.Any,
+    internal val properties: Map<String, Faker.(JavaFakerConfiguration) -> Any?> = defaultMap
 ) {
     private companion object {
 
@@ -231,6 +234,12 @@ data class JavaFakerConfiguration(
     }
 }
 
+/**
+ * # Fake object generation with `javaFakerStrategy`
+ *
+ * The faker intercepts the generation of named properties so their values can be replaced with fake data generated by
+ * the [Java Faker](https://github.com/DiUS/java-faker) library
+ */
 fun ConfigurationBuilder.javaFakerStrategy(configuration: JavaFakerConfigurationBuilder.() -> Unit = {}) {
     fakeStrategy(
         (fakeStrategy as? JavaFakerStrategy)?.new(configuration) ?: JavaFakerStrategy().new(configuration)

fixture-javafaker/src/main/kotlin/com/appmattus/kotlinfixture/decorator/fake/javafaker/JavaFakerConfigurationBuilder.kt

@@ -17,14 +17,17 @@
 package com.appmattus.kotlinfixture.decorator.fake.javafaker
 
 import com.appmattus.kotlinfixture.decorator.fake.javafaker.option.CreditCard
+import com.appmattus.kotlinfixture.decorator.fake.javafaker.option.IpAddress
 import com.appmattus.kotlinfixture.decorator.fake.javafaker.option.Temperature
 import com.appmattus.kotlinfixture.decorator.fake.javafaker.option.UserAgent
-import com.appmattus.kotlinfixture.decorator.fake.javafaker.option.IpAddress
 import com.appmattus.kotlinfixture.toUnmodifiableMap
 import com.github.javafaker.Faker
 import java.util.Locale
 
-class JavaFakerConfigurationBuilder(javaFakerConfiguration: JavaFakerConfiguration) {
+/**
+ * Builder of [JavaFakerConfiguration].
+ */
+class JavaFakerConfigurationBuilder internal constructor(javaFakerConfiguration: JavaFakerConfiguration) {
 
     /**
      * Generate `creditCard` properties in the style of the selected credit card company. See [CreditCard] for options.
@@ -77,15 +80,21 @@ class JavaFakerConfigurationBuilder(javaFakerConfiguration: JavaFakerConfigurati
 
     private val properties = javaFakerConfiguration.properties.toMutableMap()
 
+    /**
+     * Remove the [Java Faker](https://github.com/DiUS/java-faker) generator for [propertyName].
+     */
     fun removeProperty(propertyName: String) {
         properties.remove(propertyName)
     }
 
+    /**
+     * Map a [Java Faker](https://github.com/DiUS/java-faker) generator to a [propertyName].
+     */
     fun putProperty(propertyName: String, fakeGenerator: Faker.(JavaFakerConfiguration) -> Any?) {
         properties[propertyName] = fakeGenerator
     }
 
-    fun build() = JavaFakerConfiguration(
+    internal fun build() = JavaFakerConfiguration(
         creditCard = creditCard,
         ipAddress = ipAddress,
         isbn10Separator = isbn10Separator,

fixture-javafaker/src/main/kotlin/com/appmattus/kotlinfixture/decorator/fake/javafaker/JavaFakerStrategy.kt

@@ -22,7 +22,7 @@ import com.appmattus.kotlinfixture.decorator.fake.FakeStrategy
 import com.github.javafaker.Faker
 import kotlin.random.asJavaRandom
 
-open class JavaFakerStrategy(
+internal class JavaFakerStrategy(
     private val fakerConfiguration: JavaFakerConfiguration = JavaFakerConfigurationBuilder(
         JavaFakerConfiguration()
     ).build()

fixture-javafaker/src/main/kotlin/com/appmattus/kotlinfixture/decorator/fake/javafaker/option/CreditCard.kt

@@ -18,6 +18,9 @@ package com.appmattus.kotlinfixture.decorator.fake.javafaker.option
 
 import com.github.javafaker.CreditCardType
 
+/**
+ * Different types of [CreditCard]
+ */
 @Suppress("unused")
 enum class CreditCard(internal val creditCardType: CreditCardType?) {
     Any(null),

fixture-javafaker/src/main/kotlin/com/appmattus/kotlinfixture/decorator/fake/javafaker/option/IpAddress.kt

@@ -16,6 +16,9 @@
 
 package com.appmattus.kotlinfixture.decorator.fake.javafaker.option
 
+/**
+ * Different types of [IpAddress]
+ */
 enum class IpAddress {
     V4,
     V6

fixture-javafaker/src/main/kotlin/com/appmattus/kotlinfixture/decorator/fake/javafaker/option/Password.kt

@@ -16,6 +16,9 @@
 
 package com.appmattus.kotlinfixture.decorator.fake.javafaker.option
 
+/**
+ * Configuration for password generation
+ */
 data class Password(
     val minimumLength: Int = 8,
     val maximumLength: Int = 16,

fixture-javafaker/src/main/kotlin/com/appmattus/kotlinfixture/decorator/fake/javafaker/option/Temperature.kt

@@ -16,6 +16,9 @@
 
 package com.appmattus.kotlinfixture.decorator.fake.javafaker.option
 
+/**
+ * Different types of [Temperature]
+ */
 enum class Temperature {
     Celsius,
     Fahrenheit

fixture-javafaker/src/main/kotlin/com/appmattus/kotlinfixture/decorator/fake/javafaker/option/UserAgent.kt

@@ -18,6 +18,9 @@ package com.appmattus.kotlinfixture.decorator.fake.javafaker.option
 
 import com.github.javafaker.Internet
 
+/**
+ * Different types of [UserAgent]
+ */
 @Suppress("unused")
 enum class UserAgent(internal val userAgent: Internet.UserAgent?) {
     Any(null),