Vague documentation and code samples of @Default annotation as of 1.4.X #2258

I have encountered with the constructor support and the @Default annotation usage.

At the first glance (I looked at the code samples first), I had a strong feeling there is already such annotation delivered with the new version (3.9. Using Constructors), however, I had to come back to the documentation itself. These sentences confused me (emphesized mine):

If a constructor is annotated with an annotation named @Default (from any package) it will be 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) can used.

This pattern is unusual to MapStruct and unintuitive. I had to guess and experiment a bit to know I have to declare my own annotation. I think this message should be delivered more clearly for the users.

package com.mycompany.support.mapstruct;

import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;

@Retention(RetentionPolicy.CLASS)
public @interface Default {
}

The solutions are these (picking one of them should make the usage clear):

• Deliver the org.mapstruct.Default annotation itself (I understand there might be reasons against this idea, however, I haven't found any communication concluding to such reason, hence I'd like to ask for some links explaining that)
• Add the annotation definition to the documentation and explicitely state the annotation must be either created by the user or reused from a third-party library/framework with a reason behind this design.

Moreover, I propose the following one:

• Require @DefaultConstructor instead of @Default. The proposed one would be more suitable with regard to the use-case and also would not be confused with the one comming from Lombok, which a big friend with MapStruct (yet another my assumption)

I am open to submit a pull-request as soon as you point me to the relevant files to be changed as long as I am a new contributor 😄