Cleanup, added KDoc, and publish KDocs

api/build.gradle.kts

@@ -7,7 +7,11 @@ publishing {
     publications {
         create<MavenPublication>("maven") {
             artifactId = "mappie-api"
-            from(components["kotlin"])
+            from(components["java"])
         }
     }
+}
+
+java {
+    withSourcesJar()
 }

api/src/main/kotlin/io/github/mappie/api/EnumMapper.kt

@@ -2,7 +2,31 @@
 
 package io.github.mappie.api
 
+/**
+ * Base class for enum mappers. See the [documentation](https://mr-mappie.github.io/mappie/enum-mapping/enum-mapping-overview/)
+ * for a complete overview of how to generate enum mappers.
+ *
+ * For example
+ * ```kotlin
+ * class PersonMapper : EnumMapper<Color, Colour>() {
+ *      override fun map(from: Color) = mapping()
+ * }
+ * ```
+ * will generate a mapper from `Color` to `Colour`, assuming both `Color` and `Colour` have a resolvable mapping.
+ *
+ * @param FROM the source type to map from.
+ * @param TO the target type to map to.
+ */
 abstract class EnumMapper<FROM: Enum<*>, TO : Enum<*>> : Mapper<FROM, TO>() {
 
+    /**
+     * Explicitly construct a mapping to [TO] from source entry [source].
+     *
+     * For example
+     * ```kotlin
+     * Color.UNKNOWN mappedFromEnumEntry Color.ORANGE
+     * ```
+     * will generate an explicit mapping, mapping `Color.ORANGE` to `Color.UNKNOWN`.
+     */
     protected infix fun TO.mappedFromEnumEntry(source: FROM): EnumMapper<FROM, TO> = generated()
 }

api/src/main/kotlin/io/github/mappie/api/Mapper.kt

@@ -4,11 +4,29 @@ package io.github.mappie.api
 
 abstract class Mapper<FROM, TO> {
 
+    /**
+     * Map [from] to an instance of [TO].
+     *
+     * @param from the source value.
+     * @return [from] mapped to an instance of [TO].
+     */
     abstract fun map(from: FROM): TO
 
+    /**
+     * Map each element in [from] to an instance of [TO].
+     *
+     * @param from the source values.
+     * @return [from] mapped to a list of instances of [TO].
+     */
     fun mapList(from: List<FROM>): List<TO> =
         ArrayList<TO>(from.size).apply { from.forEach { add(map(it)) } }
 
+    /**
+     * Mapping function which instructs Mappie to generate code for this implementation.
+     *
+     * @param builder the configuration for the generation of this mapping.
+     * @return An instance of the mapped value at runtime.
+     */
     protected fun mapping(builder: Mapper<FROM, TO>.() -> Unit = { }): TO = generated()
 }
 

api/src/main/kotlin/io/github/mappie/api/ObjectMapper.kt

@@ -4,27 +4,80 @@ package io.github.mappie.api
 
 import kotlin.reflect.KProperty1
 
-abstract class CollectionMapper<FROM, TO> : Mapper<List<FROM>, List<TO>>() {
-
-    abstract infix fun filteredBy(predicate: (FROM) -> Boolean): CollectionMapper<FROM, TO>
-}
+/**
+ * Base mapper class for list mappers. Cannot be instantiated, but can be created by using the field [ObjectMapper.forList].
+ */
+sealed class ListMapper<FROM, TO> : Mapper<List<FROM>, List<TO>>()
 
+/**
+ * Base class for object mappers. See the [documentation](https://mr-mappie.github.io/mappie/object-mapping/object-mapping-overview/)
+ * for a complete overview of how to generate object mappers.
+ *
+ * For example
+ * ```kotlin
+ * class PersonMapper : ObjectMapper<PersonDto, Person>() {
+ *      override fun map(from: PersonDto) = mapping()
+ * }
+ * ```
+ * will generate a mapper from `PersonDto` to `Person`, assuming both `PersonDto` and `Person` have a resolvable mapping.
+ *
+ * @param FROM the source type to map from.
+ * @param TO the target type to map to.
+ */
 abstract class ObjectMapper<FROM, TO> : Mapper<FROM, TO>() {
 
-    val forList: CollectionMapper<FROM, TO> get() =
+    /**
+     * A mapper for [List] to be used in [TransformableValue.via].
+     */
+    val forList: ListMapper<FROM, TO> get() =
         error("The mapper forList should only be used in the context of 'via'. Use mapList instead.")
 
+    /**
+     * Explicitly construct a mapping to [TO] from property source [source].
+     *
+     * For example
+     * ```kotlin
+     * Person::name mappedFromProperty PersonDto::fullName
+     * ```
+     * will generate an explicit mapping, setting constructor parameter `Person.name` to `PersonDto.fullName`.
+     */
     protected infix fun <TO_TYPE, FROM_TYPE> KProperty1<TO, TO_TYPE>.mappedFromProperty(source: KProperty1<FROM, FROM_TYPE>): TransformableValue<FROM_TYPE, TO_TYPE> =
         generated()
 
-    protected infix fun <TO_TYPE> KProperty1<TO, TO_TYPE>.mappedFromConstant(value: TO_TYPE): ObjectMapper<FROM, TO_TYPE> =
+    /**
+     * Explicitly construct a mapping to [TO] from constant source [value].
+     *
+     * For example
+     * ```kotlin
+     * Person::name mappedFromConstant "John Doe"
+     * ```
+     * will generate an explicit mapping, setting constructor parameter `Person.name` to `"John Doe"`.
+     */
+    protected infix fun <TO_TYPE> KProperty1<TO, TO_TYPE>.mappedFromConstant(value: TO_TYPE): Unit =
         generated()
 
-    protected infix fun <TO_TYPE> KProperty1<TO, TO_TYPE>.mappedFromExpression(function: (FROM) -> TO_TYPE): ObjectMapper<FROM, TO_TYPE> =
+    /**
+     * Explicitly construct a mapping to [TO] from expression source [function].
+     *
+     * For example
+     * ```kotlin
+     * Person::name mappedFromConstant { personDto -> personDto.fullName + " (full)" }
+     * ```
+     * will generate an explicit mapping, setting constructor parameter `Person.name` to `"John Doe (full)"`,
+     * assuming `personDto.fullName == "John Doe"`.
+     */
+    protected infix fun <TO_TYPE> KProperty1<TO, TO_TYPE>.mappedFromExpression(function: (FROM) -> TO_TYPE): Unit =
         generated()
 
+    /**
+     * Reference a constructor parameter in lieu of a property reference, if it not exists as a property.
+     *
+     * For example
+     * ```kotlin
+     * parameter("name") mappedFromProperty PersonDto::fullName
+     * ```
+     * will generate an explicit mapping, setting constructor parameter `name` to `PersonDto.fullName`.
+     */
     protected fun parameter(name: String): KProperty1<TO, *> =
         generated()
-
-    protected fun result(source: TO): ObjectMapper<FROM, TO> = generated()
 }

api/src/main/kotlin/io/github/mappie/api/TransformableValue.kt

@@ -1,6 +1,12 @@
 package io.github.mappie.api
 
+/**
+ * The result of an explicit mapping definition which can be transformed.
+ */
 class TransformableValue<FROM, TO> {
+    /**
+     *
+     */
     infix fun transform(function: (FROM) -> TO): Unit = generated()
 
     infix fun <M : Mapper<FROM, TO>> via(clazz: M): M = generated()

compiler-plugin/src/main/kotlin/io/github/mappie/resolving/Identifiers.kt

@@ -16,8 +16,6 @@ val IDENTIFIER_MAPPED_FROM_CONSTANT = Name.identifier("mappedFromConstant")
 
 val IDENTIFIER_MAPPED_FROM_EXPRESSION = Name.identifier("mappedFromExpression")
 
-val IDENTIFIER_RESULT = Name.identifier("result")
-
 val IDENTIFIER_PARAMETER = Name.identifier("parameter")
 
 val IDENTIFIER_TRANFORM = Name.identifier("transform")

compiler-plugin/src/main/kotlin/io/github/mappie/resolving/primitives/PrimitiveBodyCollector.kt

@@ -2,7 +2,6 @@ package io.github.mappie.resolving.primitives
 
 import io.github.mappie.BaseVisitor
 import io.github.mappie.resolving.IDENTIFIER_MAPPING
-import io.github.mappie.resolving.IDENTIFIER_RESULT
 import io.github.mappie.util.irGet
 import org.jetbrains.kotlin.ir.backend.js.utils.valueArguments
 import org.jetbrains.kotlin.ir.declarations.IrFunction
@@ -26,9 +25,6 @@ class PrimitiveBodyCollector(
                 expression.valueArguments.first()?.accept(data)
                     ?: irGet(declaration.valueParameters.first())
             }
-            IDENTIFIER_RESULT -> {
-                expression.valueArguments.first()!!
-            }
             else -> {
                 super.visitCall(expression, data)
             }

testing/src/main/kotlin/testing/ListMapper.kt

@@ -15,7 +15,5 @@ object BookMapper : ObjectMapper<Book, BookDto>() {
 }
 
 object PageMapper : ObjectMapper<Page, String>() {
-    override fun map(from: Page): String = mapping {
-        result(from.text)
-    }
+    override fun map(from: Page): String = from.text
 }

testing/src/main/kotlin/testing/PrimitiveMapper.kt

@@ -4,14 +4,10 @@ import io.github.mappie.api.ObjectMapper
 
 object IntMapper : ObjectMapper<Int, String>() {
 
-    override fun map(from: Int) = mapping {
-        result(from.toString())
-    }
+    override fun map(from: Int) = from.toString()
 }
 
 object StringMapper : ObjectMapper<String, Int>() {
 
-    override fun map(from: String) = mapping {
-        result(from.toInt())
-    }
+    override fun map(from: String) = from.toInt()
 }

website/src/posts/enum-mapping/posts/overview.md

@@ -4,7 +4,7 @@ summary: "Performing enum mapping."
 eleventyNavigation:
   key: Enum Mapping Overview
   parent: Enum Mapping
-  order: 8
+  order: 9
 ---
 
 Mappie supports mapping an enum class to another enum class. This can be achieved by implementing a mapper object which

website/src/posts/object-mapping/posts/configuration.md

@@ -0,0 +1,8 @@
+---
+title: "Object Mapping Configuration"
+summary: "Object Mapping Configuration."
+eleventyNavigation:
+  key: Object Mapping Configuration
+  parent: Object Mapping
+  order: 8
+---

website/src/posts/object-mapping/posts/reusing.md

@@ -1,6 +1,6 @@
 ---
 title: "Reusing Mappers"
-summary: "Resolving source- and target properties."
+summary: "Reusing other mappers."
 eleventyNavigation:
   key: Reusing Mappers
   parent: Object Mapping