From 164535e3542f2fab0543eed2da4a3bc1fb32ccd9 Mon Sep 17 00:00:00 2001
From: Nikolas Charalambidis <nikolas.charalambidis@gmail.com>
Date: Wed, 11 Nov 2020 22:28:53 +0100
Subject: [PATCH] Add Lombok subsection in the documentation (#2266)

---
 ...er-14-third-party-api-integration.asciidoc | 151 +++++++++++++++++-
 .../chapter-3-defining-a-mapper.asciidoc      |   3 +-
 2 files changed, 152 insertions(+), 2 deletions(-)

diff --git a/documentation/src/main/asciidoc/chapter-14-third-party-api-integration.asciidoc b/documentation/src/main/asciidoc/chapter-14-third-party-api-integration.asciidoc
index 03e18167e..c31424a0d 100644
--- a/documentation/src/main/asciidoc/chapter-14-third-party-api-integration.asciidoc
+++ b/documentation/src/main/asciidoc/chapter-14-third-party-api-integration.asciidoc
@@ -38,4 +38,153 @@ public @interface Default {
 
 }
 ----
-====
\ No newline at end of file
+====
+
+[[lombok]]
+=== Lombok
+
+MapStruct works together with https://projectlombok.org/[Project Lombok] as of MapStruct 1.2.0.Beta1 and Lombok 1.16.14.
+
+MapStruct takes advantage of generated getters, setters, and constructors and uses them to generate the mapper implementations.
+
+[NOTE]
+====
+Lombok 1.18.16 introduces a breaking change (https://projectlombok.org/changelog[changelog]).
+The additional annotation processor `lombok-mapstruct-binding` (https://mvnrepository.com/artifact/org.projectlombok/lombok-mapstruct-binding[Maven]) must be added otherwise MapStruct stops working with Lombok.
+This resolves the compilation issues of Lombok and MapStruct modules.
+
+[source, xml]
+----
+<path>
+    <groupId>org.projectlombok</groupId>
+    <artifactId>lombok-mapstruct-binding</artifactId>
+    <version>0.1.0</version>
+</path>
+----
+====
+
+==== Set up
+
+The set up using Maven or Gradle does not differ from what is described in <<setup>>. Additionally, you need to provide Lombok dependencies.
+
+.Maven configuration
+====
+[source, xml, linenums]
+[subs="verbatim,attributes"]
+----
+
+<properties>
+    <org.mapstruct.version>{mapstructVersion}</org.mapstruct.version>
+    <org.projectlombok.version>1.18.16</org.projectlombok.version>
+    <maven.compiler.source>1.8</maven.compiler.source>
+    <maven.compiler.target>1.8</maven.compiler.target>
+</properties>
+
+<dependencies>
+    <dependency>
+        <groupId>org.mapstruct</groupId>
+        <artifactId>mapstruct</artifactId>
+        <version>${org.mapstruct.version}</version>
+    </dependency>
+
+    <!-- lombok dependency should not end up on classpath -->
+    <dependency>
+        <groupId>org.projectlombok</groupId>
+        <artifactId>lombok</artifactId>
+        <version>${org.projectlombok.version}</version>
+        <scope>provided</scope>
+    </dependency>
+</dependencies>
+
+<build>
+    <plugins>
+        <plugin>
+            <groupId>org.apache.maven.plugins</groupId>
+            <artifactId>maven-compiler-plugin</artifactId>
+            <version>3.8.1</version>
+            <configuration>
+                <source>1.8</source>
+                <target>1.8</target>
+                <annotationProcessorPaths>
+                    <path>
+                        <groupId>org.mapstruct</groupId>
+                        <artifactId>mapstruct-processor</artifactId>
+                        <version>${org.mapstruct.version}</version>
+                    </path>
+                    <path>
+                        <groupId>org.projectlombok</groupId>
+                        <artifactId>lombok</artifactId>
+                        <version>${org.projectlombok.version}</version>
+                    </path>
+
+                    <!-- additional annotation processor required as of Lombok 1.18.16 -->
+                    <path>
+                        <groupId>org.projectlombok</groupId>
+                        <artifactId>lombok-mapstruct-binding</artifactId>
+                        <version>0.1.0</version>
+                    </path>
+                </annotationProcessorPaths>
+            </configuration>
+        </plugin>
+    </plugins>
+</build>
+----
+====
+
+.Gradle configuration (3.4 and later)
+====
+[source, groovy, linenums]
+[subs="verbatim,attributes"]
+----
+
+dependencies {
+
+    implementation "org.mapstruct:mapstruct:${mapstructVersion}"
+    implementation "org.projectlombok:lombok:1.18.16"
+    annotationProcessor "org.projectlombok:lombok-mapstruct-binding:0.1.0"
+    annotationProcessor "org.mapstruct:mapstruct-processor:${mapstructVersion}"
+    annotationProcessor "org.projectlombok:lombok:1.18.16"
+}
+
+----
+====
+
+The usage combines what you already know from <<defining-mapper>> and Lombok.
+
+.Usage of MapStruct with Lombok
+====
+[source, java, linenums]
+[subs="verbatim,attributes"]
+----
+@Data
+public class Source {
+
+    private String test;
+}
+
+public class Target {
+
+    private Long testing;
+
+    public Long getTesting() {
+        return testing;
+    }
+
+    public void setTesting( Long testing ) {
+        this.testing = testing;
+    }
+}
+
+@Mapper
+public interface SourceTargetMapper {
+
+    SourceTargetMapper MAPPER = Mappers.getMapper( SourceTargetMapper.class );
+
+    @Mapping( source = "test", target = "testing" )
+    Target toTarget( Source s );
+}
+
+----
+====
+
+A working example can be found on the GitHub project https://github.com/mapstruct/mapstruct-examples/tree/master/mapstruct-lombok[mapstruct-lombok].
diff --git a/documentation/src/main/asciidoc/chapter-3-defining-a-mapper.asciidoc b/documentation/src/main/asciidoc/chapter-3-defining-a-mapper.asciidoc
index acdfd9817..be3435b54 100644
--- a/documentation/src/main/asciidoc/chapter-3-defining-a-mapper.asciidoc
+++ b/documentation/src/main/asciidoc/chapter-3-defining-a-mapper.asciidoc
@@ -516,7 +516,8 @@ public class PersonMapperImpl implements PersonMapper {
 
 Supported builder frameworks:
 
-* https://projectlombok.org/[Lombok] - requires having the Lombok classes in a separate module. See for more information https://github.com/rzwitserloot/lombok/issues/1538[rzwitserloot/lombok#1538]
+* https://projectlombok.org/[Lombok] - It is required to have the Lombok classes in a separate module.
+See for more information at https://github.com/rzwitserloot/lombok/issues/1538[rzwitserloot/lombok#1538] and to set up Lombok with MapStruct, refer to <<lombok>>.
 * https://github.com/google/auto/blob/master/value/userguide/index.md[AutoValue]
 * https://immutables.github.io/[Immutables] - When Immutables are present on the annotation processor path then the `ImmutablesAccessorNamingStrategy` and `ImmutablesBuilderProvider` would be used by default
 * https://github.com/google/FreeBuilder[FreeBuilder] - When FreeBuilder is present on the annotation processor path then the `FreeBuilderAccessorNamingStrategy` would be used by default.