doc: adding dokka doc + generator pipeline (#14)

.github/workflows/generate_docs.yml

@@ -0,0 +1,28 @@
+name: Generate Documentation
+on:
+  release:
+    types:
+      - prereleased
+      - released
+jobs:
+  build-documentation:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-java@v2
+        with:
+          distribution: 'adopt'
+          java-version: '17'
+      - name: Build New Documentation
+        uses: burrunan/gradle-cache-action@v1
+        with:
+          gradle-version: wrapper
+          arguments: dokkaHtmlMultiModule
+          properties: |
+            release=true
+      - name: Push New Documentation
+        uses: EndBug/add-and-commit@v7
+        with:
+          default_author: github_actions
+          branch: main
+          message: 'doc: Added Latest Documentation ✨'

.github/workflows/publish.yml

@@ -2,6 +2,8 @@ name: Publish to GitHub Packages
 on:
   push:
     branches: [ main ]
+    paths-ignore:
+      - dokka/**
 env:
   ORG_GRADLE_PROJECT_signingKey: ${{ secrets.SONATYPE_SIGNING_KEY }}
   ORG_GRADLE_PROJECT_signingPassword: ${{ secrets.SONATYPE_SIGNING_PASSWORD }}

.gitignore

@@ -6,5 +6,3 @@ build
 
 # IDE
 .idea
-
-dokka

CHANGELOG.md

@@ -4,7 +4,9 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## Unreleased - January 8th, 2022
+## [0.5.1] - January 8th, 2022
+### Added
+- Dokka Documentation
 ### Changed
 - Killed the catalog
 

gradle.properties

@@ -1,7 +1,8 @@
 # Backbone
-project.version=0.5.0
+project.version=0.5.1
 # Kotlin
 kotlin.code.style=official
 # Gradle
 org.gradle.vfs.watch=true
 org.gradle.vfs.verbose=true
+org.gradle.jvmargs=-Xmx2000m

satisfaketion-core/Module.md

@@ -0,0 +1,10 @@
+# Module satisfaketion-core
+
+## Core
+
+Contains the interfaces and Faker implementation that power Satisfaketion.
+
+# Package io.github.unredundant.satisfaketion.core
+
+Root package that contains interfaces for `Generator` and `Mutator`, along with the core `Faker` implementation and a
+number of utility extensions.

satisfaketion-core/src/main/kotlin/io/github/unredundant/satisfaketion/core/Extensions.kt

@@ -2,6 +2,9 @@ package io.github.unredundant.satisfaketion.core
 
 import kotlin.random.Random
 
+/**
+ * Collection of handy extensions used throughout the library.
+ */
 object Extensions {
   private object Alphabet {
     const val source = "abcdefghijklmnopqrstuvwxyz"
@@ -10,6 +13,9 @@ object Extensions {
   /**
    * Replaces every `#` char for this [String] receiver with a random int from 0 to 9 inclusive
    * and returns the modified [String].
+   * @param random Seed from which to generate all random values.  Defaults to [Random.Default]
+   * @receiver [String]
+   * @return "Number-ified" value
    */
   @Suppress("MagicNumber")
   fun String.numerify(random: Random = Random.Default): String {
@@ -20,14 +26,19 @@ object Extensions {
   /**
    * Replaces every `?` char for this [String] receiver with a random upper-case letter from the English alphabet
    * and returns the modified [String].
+   * @param random Seed from which to generate all random values.  Defaults to [Random.Default]
+   * @param upper flag that will convert all replaced characters to their uppercase representation.  Defaults to true
+   * @return "Letter-ified" value
    */
-  fun String.letterify(random: Random = Random.Default, isUpper: Boolean = true): String {
-    return map { if (it == '?') random.nextLetter(upper = isUpper).toString() else "$it" }
+  fun String.letterify(random: Random = Random.Default, upper: Boolean = true): String {
+    return map { if (it == '?') random.nextLetter(upper = upper).toString() else "$it" }
       .joinToString("")
   }
 
   /**
    * Returns a random letter from [Alphabet.source]
+   * @param upper flag that will convert all replaced characters to their uppercase representation.  Defaults to true
+   * @return generated [Char]
    */
   fun Random.nextLetter(upper: Boolean): Char {
     val source = if (upper) Alphabet.source.uppercase() else Alphabet.source
@@ -36,10 +47,18 @@ object Extensions {
 
   /**
    * Returns a random element of a list
+   * @receiver List from which to pick item from
+   * @param random Seed from which to generate all random values.  Defaults to [Random.Default]
+   * @return Single element [T] from receiver
    */
-  fun <T> List<T>.nextItem(random: Random): T = get(random.nextInt(size))
+  fun <T> List<T>.nextItem(random: Random = Random.Default): T = get(random.nextInt(size))
 
-  // Allows for direct mutation on an existing generator
+  /**
+   * Allows for a [Mutator] to be applied directly to a given [Generator]
+   * @receiver [Generator] of type [T]
+   * @param mut [Mutator] that takes the receiver and returns a [Generator] of type [TT]
+   * @return [Generator] of type [TT]
+   */
   fun <T, TT> Generator<T>.mutate(mut: Mutator<T, TT>): Generator<TT> {
     return mut.mutate(this)
   }

satisfaketion-core/src/main/kotlin/io/github/unredundant/satisfaketion/core/Faker.kt

@@ -6,18 +6,30 @@ import kotlin.reflect.KParameter
 import kotlin.reflect.KProperty1
 import kotlin.reflect.full.primaryConstructor
 
+/**
+ * Faker implementation.  Responsible for generating full objects out of a set of provided [Generator] instances.
+ * @param clazz [KClass] of type [T].  Used to provide type safety and perform reflective analysis
+ */
 class Faker<T : Any>(private val clazz: KClass<T>) {
 
   private var propertyMap: Map<KParameter, Generator<*>> = emptyMap()
   private var cache: MutableMap<KParameter, Any?> = mutableMapOf()
 
   companion object {
+    /**
+     * Allows for streamlined [Faker] invocation, leveraging a reified [T] to instantiate the [Faker]
+     */
     inline operator fun <reified T : Any> invoke(init: Faker<T>.() -> Unit): Faker<T> {
       val builder = Faker(T::class)
       return builder.apply(init)
     }
   }
 
+  /**
+   * Generates an instance of [T] using the [Generator] instances registered via [Faker.invoke]
+   * @param seed [Random] to be passed to each [Generator] in order to enable deterministic generation
+   * @return Instance of [T] containing all registered generated values
+   */
   fun generate(seed: Random = Random.Default): T {
     val constructor = clazz.primaryConstructor ?: error("$clazz does not have a primary constructor, cannot generate")
     val generatedParams = propertyMap.mapValues { (k, v) ->
@@ -33,6 +45,11 @@ class Faker<T : Any>(private val clazz: KClass<T>) {
     return constructor.callBy(generatedParams)
   }
 
+  /**
+   * Binds a [KProperty1] to the specified [Generator].  Stored by the [Faker] to
+   * be used in each invocation of [Faker.generate].
+   * @param init Function parameter that is invoked in order to register the provided [Generator]
+   */
   operator fun <R> KProperty1<T, R>.invoke(init: (KProperty1<T, R>) -> Generator<R>) {
     val param = clazz.primaryConstructor?.parameters?.find { it.name == name }
       ?: error("Unable to match $name to a parameter for $clazz")
@@ -46,6 +63,13 @@ class Faker<T : Any>(private val clazz: KClass<T>) {
     private var prop: KProperty1<T, R>
     private var invoke: (R, Random) -> RR
 
+    /**
+     * This constructor enables users to nest a [CorrelatedPropertyGenerator].
+     * Doing so results in a correlation chain by
+     * which all required values are generated ahead of the correlated [Generator].
+     * @param prop [KProperty1] with which to correlate this [Generator]
+     * @param invoke Function parameter providing access to the nested [Generator]
+     */
     constructor(
       prop: KProperty1<T, R>,
       invoke: (R) -> Generator<RR>
@@ -56,6 +80,11 @@ class Faker<T : Any>(private val clazz: KClass<T>) {
       }
     }
 
+    /**
+     * This constructor enables direct correlation with a desired [Generator]
+     * @param prop [KProperty1] with which to correlate this [Generator]
+     * @param invoke Function parameter used to provide the correlated value for use in the underlying [Generator]
+     */
     constructor(
       prop: KProperty1<T, R>,
       invoke: (R, Random) -> RR,
@@ -64,6 +93,11 @@ class Faker<T : Any>(private val clazz: KClass<T>) {
       this.invoke = invoke
     }
 
+    /**
+     * Implementation of the [Generator] interface, allowing for the correlated generator to be invoked on the fly once
+     * provided with the requisite data.
+     * @param seed Will be provided by correlated [Generator]
+     */
     override fun generate(seed: Random): RR {
       val param = clazz.primaryConstructor?.parameters?.find { it.name == prop.name }
         ?: error("Unable to match ${prop.name} to a parameter for $clazz")

settings.gradle.kts

@@ -5,4 +5,3 @@ include("satisfaketion-mutators")
 
 // Feature Previews
 enableFeaturePreview("TYPESAFE_PROJECT_ACCESSORS")
-enableFeaturePreview("VERSION_CATALOGS")