Updated documentation structure

website/src/_data/navigation.json

@@ -32,13 +32,33 @@
       "items": [
         {
           "caption": "Object Mapping",
-          "url": "/usage/object-mapping/",
+          "url": "/object-mapping/overview/",
           "external": false
         },
         {
           "caption": "Enum Mapping",
-          "url": "/usage/enum-mapping/",
+          "url": "/enum-mapping/overview/",
           "external": false
+        },
+        {
+          "caption": "Primitive Mapping",
+          "url": "/primitive-mapping/overview/",
+          "external": false
+        }
+      ]
+    },
+    {
+      "title": "Contact",
+      "items": [
+        {
+          "caption": "Submit a Bug or Feature Request",
+          "url": "https://github.com/Mr-Mappie/mappie/issues/new/choose",
+          "external": true
+        },
+        {
+          "caption": "Start a Discussion",
+          "url": "https://github.com/Mr-Mappie/mappie/discussions/new/choose",
+          "external": true
         }
       ]
     }

website/src/_includes/layouts/front-page.html

@@ -37,7 +37,7 @@ <h3 class="accordion-card__title">{{ faq.title }}</h3>
         {% endif %}
         <div>
             <h2>Acknowledgements</h2>
-            <p>This documentation page is based on the <a href="https://github.com/conedevelopment/sprucecss-eleventy-documentation-template">template</a> of <a href="https://conedevelopment.com/">Cone</a>.</p>
+            <p>This documentation page is based on the <a href="https://github.com/conedevelopment/sprucecss-eleventy-documentation-template">template</a> by <a href="https://conedevelopment.com/">Cone</a>.</p>
         </div>
     </div>
 {% endblock %}

website/src/index.md

@@ -18,4 +18,16 @@ overview:
     title: "Getting Started"
     url: "/getting-started/"
     description: "Start here and get to know Mappie."
+-
+  title: "Object Mapping"
+  url: "/object-mapping/"
+  description: "Learn how to use Mappie for object mapping."
+-
+  title: "Enum Mapping"
+  url: "/enum-mapping/"
+  description: "Learn how to use Mappie for enum mapping."
+-
+  title: "Primitive Mapping"
+  url: "/primitive-mapping/"
+  description: "Learn how to use Mappie for primitive mapping."
 ---

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

@@ -0,0 +1,6 @@
+---
+title: "Enum Mapping"
+eleventyNavigation:
+  key: Enum Mapping
+  order: 3
+---

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

@@ -0,0 +1,21 @@
+---
+title: "Enum Mapping Configuration"
+summary: "Enum mapping configuration."
+eleventyNavigation:
+  key: Enum Mapping Configuration
+  parent: Enum Mapping
+  order: 10
+---
+
+By default, all enum sources must have a defined target. This can be disabled by adding the following
+configuration to the `build.gradle.kts` file
+
+```kotlin
+mappie {
+    strictness {
+        enums = false // Disable validating that all enum sources have a corresponding target 
+    }
+}
+```
+
+Note that this might result in a [NoWhenBranchMatchedException](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-no-when-branch-matched-exception/) exception being thrown at runtime.

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

@@ -0,0 +1,28 @@
+---
+title: "Entry Mapping"
+summary: "Mapping enum entry values."
+eleventyNavigation:
+  key: Entry Mapping
+  parent: Enum Mapping
+  order: 9
+---
+
+Not all enums classes that one wants to map have identical entries. If this is the case,
+Mappie cannot determine which source must map to which target.
+
+Suppose `Color` has an extra entry `Color.ORANGE`, whilst `Colour` does
+not have `Colour.ORANGE`, but does have `Colour.OTHER`. In other words 
+```kotlin
+enum class Color { RED, GREEN, BLUE, ORANGE; }
+
+enum class Colour { RED, GREEN, BLUE, OTHER; }
+```
+
+We can generate a complete mapper by mapping `Colour.ORANGE` to `Colour.OTHER` via `mappedFromEnumEntry`
+```kotlin
+object ColorMapper : EnumMapper<Color, Colour>() {
+    override fun map(from: Color): Colour = mapping {
+        Colour.OTHER mappedFromEnumEntry Color.ORANGE
+    }
+}
+```

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

@@ -0,0 +1,29 @@
+---
+title: "Enum Mapping Overview"
+summary: "Performing enum mapping."
+eleventyNavigation:
+  key: Enum Mapping Overview
+  parent: Enum Mapping
+  order: 8
+---
+
+Mappie supports mapping an enum class to another enum class. This can be achieved by implementing a mapper object which
+extends from `EnumMapper`.
+
+The mappings of the enum entries are resolved by name. For example, when constructing a mapper for the enum 
+classes `Color`
+```kotlin
+enum class Color { RED, GREEN, BLUE; }
+```
+and `Colour`
+```kotlin
+enum class Colour { RED, GREEN, BLUE; }
+```
+Mappie will resolve all mappings automatically, as the enum classes have identical entries. 
+
+This can be achieved by writing the following enum mapper
+```kotlin
+object ColorMapper : EnumMapper<Color, Colour>() {
+    override fun map(from: Color): Colour = mapping()
+}
+```

website/src/posts/enum-mapping/posts/posts.json

@@ -0,0 +1,4 @@
+{
+  "layout": "layouts/post.html",
+  "permalink": "/enum-mapping/{{ title | slug }}/index.html"
+}

website/src/posts/usage/posts/object-mapping.md → website/src/posts/object-mapping/object-mapping.md

@@ -1,9 +1,6 @@
 ---
 title: "Object Mapping"
-summary: "Performing object mapping."
 eleventyNavigation:
   key: Object Mapping
-  parent: Usage
-  order: 3
+  order: 2
 ---
-

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

@@ -0,0 +1,8 @@
+---
+title: "Lists, Sets & More"
+summary: "Resolving source- and target properties."
+eleventyNavigation:
+  key: Lists, Sets & More
+  parent: Object Mapping
+  order: 7
+---

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

@@ -0,0 +1,64 @@
+---
+title: "Object Mapping Overview"
+summary: "Performing object mapping."
+eleventyNavigation:
+  key: Object Mapping Overview
+  parent: Object Mapping
+  order: 3
+---
+
+Mappie supports creating data object mappers via the base class `DataClassMapper`.
+
+Suppose we have a data class `Person`
+```kotlin
+data class Person(val name: String, val age: Int)
+```
+and a data class `PersonDto`
+```kotlin
+data class PersonDto(val name: String, val age: Int)
+```
+The fields of `Person` match those of `PersonDto`, and as such, not mappings have to be defined, for example
+```kotlin
+object PersonMapper : DataClassMapper<Person, PersonDto>() {
+    override fun map(from: Person): PersonDto = mapping()
+}
+```
+
+## Unresolved properties
+Not all data classes you want to map are equivalent. Suppose the target class `PersonDto` has the property `description`, which is not defined in `Person`
+```kotlin
+data class PersonDto(
+    val name: String, 
+    val age: Int, 
+    val description: String,
+)
+```
+
+Mappie will throw an error stating that the target `description` has no source defined.
+
+This can be addressed in multiple ways. 
+
+### Explicit property mapping via another property
+A possibility is to map `description` from another property, e.g. via `name`
+
+```kotlin
+object PersonMapper : DataClassMapper<Person, PersonDto>() {
+    override fun map(from: Person): PersonDto = mapping {
+        PersonDto::description mappedFromProperty Person::name
+    }
+}
+```
+
+### Explicit property mapping via an expression
+A possibility is to map `description` from an expression, e.g. setting it to the constant `"unknown"`
+
+```kotlin
+object PersonMapper : DataClassMapper<Person, PersonDto>() {
+    override fun map(from: Person): PersonDto = mapping {
+        PersonDto::description mappedFromExpression { source -> "unknown" }
+    }
+}
+```
+the parameter of the lambda `source` is equal to `from`. It does not have to be named.
+
+## Configuration

website/src/posts/object-mapping/posts/posts.json

@@ -0,0 +1,4 @@
+{
+  "layout": "layouts/post.html",
+  "permalink": "/object-mapping/{{ title | slug }}/index.html"
+}

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

@@ -0,0 +1,8 @@
+---
+title: "Resolving"
+summary: "Resolving source- and target properties."
+eleventyNavigation:
+  key: Resolving
+  parent: Object Mapping
+  order: 4
+---

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

@@ -0,0 +1,8 @@
+---
+title: "Reusing Mappers"
+summary: "Resolving source- and target properties."
+eleventyNavigation:
+  key: Reusing Mappers
+  parent: Object Mapping
+  order: 5
+---

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

@@ -0,0 +1,8 @@
+---
+title: "Transforming"
+summary: "Transforming source properties."
+eleventyNavigation:
+  key: Transforming
+  parent: Object Mapping
+  order: 6
+---

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

@@ -0,0 +1,9 @@
+---
+title: "Primitive Mapping Overview"
+summary: "Performing primitive mapping."
+eleventyNavigation:
+  key: Primitive Mapping Overview
+  parent: Primitive Mapping
+  order: 11
+---
+

website/src/posts/primitive-mapping/posts/posts.json

@@ -0,0 +1,4 @@
+{
+  "layout": "layouts/post.html",
+  "permalink": "/primitive-mapping/{{ title | slug }}/index.html"
+}

website/src/posts/primitive-mapping/primitive-mapping.md

@@ -0,0 +1,6 @@
+---
+title: "Primitive Mapping"
+eleventyNavigation:
+  key: Primitive Mapping
+  order: 4
+---