#945 Extension of chapter 3.2

This commit extends the description of section 3.2 with the possibility
to declare custom mapping methods as default methods in the interface
directly.

documentation/src/main/asciidoc/mapstruct-reference-guide.asciidoc

@@ -332,15 +332,39 @@ Collection-typed attributes with the same element type will be copied by creatin
 
 MapStruct takes all public properties of the source and target types into account. This includes properties declared on super-types.
 
-[[mappers-from-abstract-classes]]
-=== Generating mappers from abstract classes
+[[adding-custom-methods]]
+=== Adding custom methods to mappers
 
 In some cases it can be required to manually implement a specific mapping from one type to another which can't be generated by MapStruct. One way for this is to implement such method on another class which then is used by mappers generated by MapStruct (see <<invoking-other-mappers>>).
 
-Alternatively you can define a mapper in form of an abstract class instead of an interface and implement custom methods directly in this mapper class. In this case MapStruct will generate an extension of the abstract class with implementations of all abstract methods.
+Alternatively you can implement custom methods directly in a mapper interface as default methods. The generated code will invoke the default methods if the argument and return types match.
 
 As an example let's assume the mapping from `Person` to `PersonDto` requires some special logic which can't be generated by MapStruct. You could then define the mapper from the previous example like this:
 
+.Mapper which defines a custom mapping with a default method
+====
+[source, java, linenums]
+[subs="verbatim,attributes"]
+----
+@Mapper
+public interface CarMapper {
+
+    @Mappings({...})
+    CarDto carToCarDto(Car car);
+
+    default PersonDto personToPersonDto(Person person) {
+        //hand-written mapping logic
+    }
+}
+----
+====
+
+The class generated by MapStruct implements method `carToCarDto()`. The generated code in `carToCarDto()` will invoke the manually implemented `personToPersonDto()` method when mapping the `driver` attribute.
+
+A mapper could also be defined in form of an abstract class instead of an interface and implement custom methods directly in this mapper class. In this case MapStruct will generate an extension of the abstract class with implementations of all abstract methods. An advantage of this approach over declaring default methods is that additional fields could be declared in the mapper class.
+
+The previous example where the mapping from `Person` to `PersonDto` requires some special logic could then be defined like this:
+
 .Mapper defined by an abstract class
 ====
 [source, java, linenums]