#2258 Fixes vague description of @Default and @ConstructorProperties annotations

documentation/src/main/asciidoc/chapter-14-third-party-api-integration.asciidoc

@@ -0,0 +1,41 @@
+[[third-party-api-integration]]
+== Third-party API integration
+
+[[non-shipped-annotations]]
+=== Non-shipped annotations
+
+There are various use-cases you must resolve ambiguity for MapStruct to use a correct piece of code.
+However, the primary goal of MapStruct is to focus on bean mapping without polluting the entity code.
+For that reason, MapStruct is flexible enough to interact with already defined annotations from third-party libraries.
+The requirement to enable this behavior is to match the _name_ of such annotation.
+Hence, we say that annotation can be _from any package_.
+
+The annotations _named_ `@ConstructorProperties` and `@Default` are currently examples of this kind of annotation.
+
+[WARNING]
+====
+If such named third-party annotation exists, it does not guarantee its `@Target` matches with the intended placement.
+Be aware of placing a third-party annotation just for sake of mapping is not recommended as long as it might lead to unwanted side effects caused by that library.
+====
+
+A very common case is that no third-party dependency imported to your project provides such annotation or is inappropriate for use as already described.
+In such cases create your own annotation, for example:
+
+====
+[source, java, linenums]
+[subs="verbatim,attributes"]
+----
+package foo.support.mapstruct;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+@Target(ElementType.CONSTRUCTOR)
+@Retention(RetentionPolicy.CLASS)
+public @interface Default {
+
+}
+----
+====

documentation/src/main/asciidoc/chapter-3-defining-a-mapper.asciidoc

@@ -537,10 +537,10 @@ When doing a mapping MapStruct checks if there is a builder for the type being m
 If there is no builder, then MapStruct looks for a single accessible constructor.
 When there are multiple constructors then the following is done to pick the one which should be used:
 
-* If a constructor is annotated with an annotation named `@Default` (from any package) it will be used.
+* If a constructor is annotated with an annotation _named_ `@Default` (from any package, see <<non-shipped-annotations>>) it will be used.
 * If a single public constructor exists then it will be used to construct the object, and the other non public constructors will be ignored.
 * If a parameterless constructor exists then it will be used to construct the object, and the other constructors will be ignored.
-* If there are multiple eligible constructors then there will be a compilation error due to ambiguous constructors. In order to break the ambiguity an annotation named `@Default` (from any package) can used.
+* If there are multiple eligible constructors then there will be a compilation error due to ambiguous constructors. In order to break the ambiguity an annotation _named_ `@Default` (from any package, see <<non-shipped-annotations>>) can used.
 
 .Deciding which constructor to use
 ====
@@ -585,7 +585,7 @@ public class Van {
 ====
 
 When using a constructor then the names of the parameters of the constructor will be used and matched to the target properties.
-When the constructor has an annotation named `@ConstructorProperties` (from any package) then this annotation will be used to get the names of the parameters.
+When the constructor has an annotation _named_ `@ConstructorProperties` (from any package, see <<non-shipped-annotations>>) then this annotation will be used to get the names of the parameters.
 
 [NOTE]
 ====

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

@@ -44,4 +44,6 @@ include::chapter-11-reusing-mapping-configurations.asciidoc[]
 
 include::chapter-12-customizing-mapping.asciidoc[]
 
-include::chapter-13-using-mapstruct-spi.asciidoc[]
+include::chapter-13-using-mapstruct-spi.asciidoc[]
+
+include::chapter-14-third-party-api-integration.asciidoc[]