Update mkdocs and fix noticed documentation issues

docs/Dockerfile

@@ -1,2 +1,2 @@
-FROM squidfunk/mkdocs-material:9.5.19
-RUN pip install mkdocs==1.6.0 mkdocs-macros-plugin==1.0.5
+FROM squidfunk/mkdocs-material:9.5.50
+RUN pip install mkdocs==1.6.1 mkdocs-macros-plugin==1.3.7

docs/docs/cookbook.md

@@ -2925,6 +2925,29 @@ For these cases, a proper optics library (like Quicklens) is recommended. As you
 were selected in such way that there should be no conflicts with other libraries, so you don't have to choose one - you
 can pick up both.
 
+## Patching `case class` with another instance of the same `case class`
+
+You can use 2 instances of the same `case class` to copy fields form one another - you only need to exclude some
+fields from the patching:
+
+!!! example
+
+    ```scala
+    //> using dep io.scalaland::chimney::{{ chimney_version() }}
+    //> using dep com.lihaoyi::pprint::{{ libraries.pprint }}
+    import io.scalaland.chimney.dsl._
+
+    case class Foo(a: String, b: String)
+
+    pprint.pprintln(
+      Foo("a", "b").using(Foo("c", "d"))
+        .withFieldIgnored(_.a)
+        .patch
+    )
+    // expected output:
+    // Foo(a = "a", b = "d")
+    ```
+
 ## Mixing Scala 2.13 and Scala 3 types
 
 [Scala 2.13 project can use Scala 3 artifacts and vice versa](https://docs.scala-lang.org/scala3/guides/migration/compatibility-classpath.html).
@@ -2965,30 +2988,7 @@ to contribute to easier migration from Scala 2.13 to Scala 3.
     and probably never will.
 
     It is required that there is only 1 version of Chimney on the class-path - either Scala 2 or Scala 3 version - which
-    would be called only from modules with the matching version of Scala. 
-
-## Patching `case class` with another instance of the same `case class`
-
-You can use 2 instances of the same `case class` to copy fields form one another - you only need to exclude some
-fields from the patching:
-
-!!! example
-
-    ```scala
-    //> using dep io.scalaland::chimney::{{ chimney_version() }}
-    //> using dep com.lihaoyi::pprint::{{ libraries.pprint }}
-    import io.scalaland.chimney.dsl._
-
-    case class Foo(a: String, b: String)
-
-    pprint.pprintln(
-      Foo("a", "b").using(Foo("c", "d"))
-        .withFieldIgnored(_.a)
-        .patch
-    )
-    // expected output:
-    // Foo(a = "a", b = "d")
-    ```
+    would be called only from modules with the matching version of Scala.
 
 ## Integrations
 

docs/docs/index.md

@@ -228,13 +228,34 @@ You can also merge values!
     pprint.pprintln(
       UserData("John", "Smith").into[User]
         .withFallback(UserMeta(10L, isDeleted = false))
-        .enableMacrosLogging
         .transform
     )
     // expected output:
     // User(id = 10L, isDeleted = false, name = "John", surname = "Smith")
     ```
 
+??? example
+
+    ```scala
+    // macro outputs code like this (reformatted a bit for readability):
+
+    val vector = ... // overrides stored by DSL in Vector[Any], here UserMeta fallback
+
+    final class $anon() extends Transformer[UserData, User] {
+      def transform(src: UserData): User = {
+        val userData: UserData = src
+        new User(
+          vector(0).asInstanceOf[UserMeta].id,
+          vector(0).asInstanceOf[UserMeta].isDeleted,
+          userdata.name,
+          userdata.surname
+        )
+      }
+    }
+
+    (new $anon(): Transformer[User, UserDTO])
+    ```
+
 Or patch one of them with another! 
 
 !!! example
@@ -256,8 +277,25 @@ Or patch one of them with another!
     // User(id = 10L, isDeleted = false, name = "Jane", surname = "Doe")
     ```
 
+??? example
+
+    ```scala
+    // macro outputs code like this (reformatted a bit for readability):
+    final class $anon extends Patcher[User, UserUpdate] {
+      def patch(user: User, userupdate: UserUpdate): User =
+        new User(
+          user.id,
+          userupdate.isDeleted.fold(user.isDeleted)(((boolean: Boolean) => boolean)),
+          userupdate.name.fold(user.name)(((string: String) => string)),
+          userupdate.surname.fold(user.surname)(((string: String) => string))
+        )
+    }
+
+    new $anon()
+    ```
+
 Now, visit the [quick start section](quickstart.md) to learn how to get Chimney and the move
-to the [supported transformations section](supported-transformations.md) and [supported patching section](supported-patching.md.md)
+to the [supported transformations section](supported-transformations.md) and [supported patching section](supported-patching.md)
 to learn about a plethora of transformations supported out of the box - and even more enabled with easy customizations!
 
 !!! tip

docs/docs/quickstart.md

@@ -89,13 +89,13 @@ or whe the targeted type has a private constructor. Out of the box, it supports:
  * conversions where [some transformation can fail in runtime](supported-transformations.md#total-transformers-vs-partialtransformers)
    (parsing, smart constructors)
  * [mergings multiple `case class`es or tuples into one](supported-transformations.md#merging-multiple-input-sources-into-a-single-target-value)
-   * allowing combining of [`Option`s](supported-transformations.md#merging-option-with-option-into-option)
-   * allowing combining of [`Either`s](supported-transformations.md#merging-either-with-either-into-either)
-   * allowing combining of [collections](supported-transformations.md#merging-collection-with-collection-into-collection)
+    * allowing combining of [`Option`s](supported-transformations.md#merging-option-with-option-into-option)
+    * allowing combining of [`Either`s](supported-transformations.md#merging-either-with-either-into-either)
+    * allowing combining of [collections](supported-transformations.md#merging-collection-with-collection-into-collection)
  * [patching one `case class` with another](supported-patching.md)
-   * with special handling of [`Option`s](supported-patching.md#updating-value-with-option)
-   * with special handling of [`Either`s](supported-patching.md#updating-value-with-either)
-   * with special handling of [collections](supported-patching.md#updating-value-with-collection)
+    * with special handling of [`Option`s](supported-patching.md#updating-value-with-option)
+    * with special handling of [`Either`s](supported-patching.md#updating-value-with-either)
+    * with special handling of [collections](supported-patching.md#updating-value-with-collection)
  * [previewing how Chimney attempts to generate the transformation](troubleshooting.md#debugging-macros) 
 
 [And much, much more!](supported-transformations.md)

docs/docs/supported-patching.md

@@ -400,10 +400,10 @@ If the flag was enabled in the implicit config it can be disabled with `.clearOn
 
 ### Unambiguous `Option` update
 
- The flag is not required when updating `Option[A]` with `Option[Option[B]]`, as then it is always
- unambiguous what to do:
+The flag is not required when updating `Option[A]` with `Option[Option[B]]`, as then it is always
+unambiguous what to do:
 
- !!! example
+!!! example
 
     ```scala
     //> using dep io.scalaland::chimney::{{ chimney_version() }}
@@ -556,10 +556,10 @@ If the flag was enabled in the implicit config it can be disabled with `.useLeft
 
 ### Unambiguous `Either` update
 
- The flag is not required when updating `Either[K, V]` with `Option[Either[K2, V2]]`, as then it is always
- unambiguous what to do:
+The flag is not required when updating `Either[K, V]` with `Option[Either[K2, V2]]`, as then it is always
+unambiguous what to do:
 
- !!! example
+!!! example
 
     ```scala
     //> using dep io.scalaland::chimney::{{ chimney_version() }}
@@ -697,10 +697,10 @@ If the flag was enabled in the implicit config it can be disabled with `.overrid
 
 ### Unambiguous collection update
 
- The flag is not required when updating collection with `Option[collection]`, as then it is always
- unambiguous what to do (leave unchanged or replace):
+The flag is not required when updating collection with `Option[collection]`, as then it is always
+unambiguous what to do (leave unchanged or replace):
 
- !!! example
+!!! example
 
     ```scala
     //> using dep io.scalaland::chimney::{{ chimney_version() }}

docs/docs/supported-transformations.md

@@ -1539,7 +1539,7 @@ The `None` value is used as a fallback, meaning:
 
 !!! example
 
-    Behavior when both [`.enableDefaultValues`](#allowing-the-constructors-default-values) and `.enableOptionDefaultsToNone` are used:
+    Behavior when both [`.enableDefaultValues`](#allowing-fallback-to-the-constructors-default-values) and `.enableOptionDefaultsToNone` are used:
 
     ```scala
     //> using dep io.scalaland::chimney::{{ chimney_version() }}

docs/docs/troubleshooting.md

@@ -1920,7 +1920,7 @@ Since Ducktape is inspired by Chimney, there is a huge overlap in functionality.
  * Ducktape provides/allows:
     * some linting telling the users that they overrode some things twice, or that some config cannot be used because
       another config provided value for level "above"
-    * `Field.allMatching` which has no direct counterpart in Chimney, but in many cases it could replaced using
+    * `Field.allMatching` which has no direct counterpart in Chimney, but in many cases it could be replaced by: using
       [`withFallback`](supported-transformations.md#merging-multiple-input-sources-into-a-single-target-value),
       using data from `allMatching` as the source, and source of Ducktape transformation as a fallback
  * Chimney provides/allows:
@@ -1933,7 +1933,7 @@ Since Ducktape is inspired by Chimney, there is a huge overlap in functionality.
       `_.everyMapKey` and `_.everyMapValue` would work with them (including Java collections and Cats data)
     * customizing the [field-](supported-transformations.md#customizing-field-name-matching) and
       [subtype-name](supported-transformations.md#customizing-subtype-name-matching) matching methods
-    * [sharing flags overrides between all derivations in the same scope](cookbook.md#reusing-flags-for-several-transformationspatchings)
+    * [sharing flags overrides between all derivations in the same scope](cookbook.md#reusing-the-flags-for-several-transformationspatchings)
     * [smart constructors](supported-transformations.md#types-with-manually-provided-constructors), not only custom
       constructors guaranteed to create the value
     * [`Patcher`s](supported-patching.md)

docs/docs/under-the-hood.md

@@ -570,11 +570,20 @@ rule has to look at it, and decide whether fallbacks apply and if they should be
 
 In other words, merging has to be supported separately by every rule that should allow it.
 
-`Patcher`s have been rewritten in Chimney 1.7.0 to be a specialized version of merging transformations, similar to:
+`Patcher`s have been rewritten in Chimney 1.7.0 to be a specialized version of merging transformations:
 
-```scala
-patch.into[PatchedValue].withFallback(originalValue).transform
-```
+!!! example
+
+    ```scala
+    originalValue.patchUsing(patch) // or
+    originalValue.using(patch).patch
+    ```
+
+    is similar to
+
+    ```scala
+    patch.into[PatchedValue].withFallback(originalValue).transform
+    ```
 
 but with a few changes, like e.g.:
 

docs/requirements.txt

@@ -1,3 +1,3 @@
-mkdocs==1.6.0
-mkdocs-macros-plugin==1.0.5
-mkdocs-material==9.5.19
+mkdocs==1.6.1
+mkdocs-macros-plugin==1.3.7
+mkdocs-material==9.5.50