mapstruct · filiphr · May 1, 2023 · Mar 28, 2023 · Mar 28, 2023 · Apr 22, 2023
diff --git a/core/src/main/java/org/mapstruct/Javadoc.java b/core/src/main/java/org/mapstruct/Javadoc.java
@@ -0,0 +1,115 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Allows the definition of Javadoc comments in the MapStruct <code>Mapper</code> generated class.
+ *
+ * <p>The annotation provides support for the usual Javadoc comments elements by defining analogous attributes.</p>
+ *
+ *
+ * <p>Please, note that at least one of these attributes must be specified.</p>
+ *
+ * <p>
+ * For instance, the following definition;
+ * </p>
+ * <pre><code class='java'>
+ * &#64;Javadoc(
+ *     value = "This is the description",
+ *     authors = { "author1", "author2" },
+ *     deprecated = "Use {&#64;link OtherMapper} instead",
+ *     since = "0.1"
+ * )
+ * </code></pre>
+ *
+ * <p>
+ * will generate:
+ * </p>
+ *
+ * <pre><code class='java'>
+ * /**
+ * * This is the description
+ * *
+ * * &#64;author author1
+ * * &#64;author author2
+ * *
+ * * &#64;deprecated Use {&#64;link OtherMapper} instead
+ * * &#64;since 0.1
+ * *&#47;
+ * </code></pre>
+ *
+ * <p>
+ * The entire Javadoc comment block can be passed directly:
+ * </p>
+ * <pre><code class='java'>
+ * &#64;Javadoc("This is the description\n"
+ *            + "\n"
+ *            + "&#64;author author1\n"
+ *            + "&#64;author author2\n"
+ *            + "\n"
+ *            + "&#64;deprecated Use {&#64;link OtherMapper} instead\n"
+ *            + "&#64;since 0.1\n"
+ * )
+ * </code></pre>
+ *
+ * <pre><code class='java'>
+ * // or using Text Blocks
+ * &#64;Javadoc(
+ *     """
+ *     This is the description
+ *
+ *     &#64;author author1
+ *     &#64;author author2
+ *
+ *     &#64;deprecated Use {&#64;link OtherMapper} instead
+ *     &#64;since 0.1
+ *     """
+ * )
+ * </code></pre>
+ */
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.SOURCE)
+public @interface Javadoc {
+    /**
+     * Main Javadoc comment text block.
+     *
+     * @return Main Javadoc comment text block.
+     */
+    String value() default "";
+
+    /**
+     * List of authors of the code that it is being documented.
+     * <p>
+     * It will generate a list of the Javadoc tool comment element <code>&#64;author</code>
+     * with the different values and in the order provided.
+     *
+     * @return array of javadoc authors.
+     */
+    String[] authors() default { };
+
+    /**
+     * Specifies that the functionality that is being documented is deprecated.
+     * <p>
+     * Corresponds to the <code>&#64;deprecated</code> Javadoc tool comment element.
+     *
+     * @return Deprecation message about the documented functionality
+     */
+    String deprecated() default "";
+
+    /**
+     * Specifies the version since the functionality that is being documented is available.
+     * <p>
+     * Corresponds to the <code>&#64;since</code> Javadoc tool comment element.
+     *
+     * @return Version since the functionality is available
+     */
+    String since() default "";
+}
diff --git a/core/src/main/java/org/mapstruct/Mapper.java b/core/src/main/java/org/mapstruct/Mapper.java
@@ -74,6 +74,7 @@
  * </code></pre>
  *
  * @author Gunnar Morling
+ * @see Javadoc
  */
 @Target(ElementType.TYPE)
 @Retention(RetentionPolicy.CLASS)

diff --git a/documentation/src/main/asciidoc/chapter-3-defining-a-mapper.asciidoc b/documentation/src/main/asciidoc/chapter-3-defining-a-mapper.asciidoc
@@ -761,3 +761,103 @@ public class MyConverterImpl implements MyConverter {
 }
 ----
 ====
+
+
+[[javadoc]]
+=== Adding Javadoc comments
+
+MapStruct provides support for defining Javadoc comments in the generated mapper implementation using the
+`org.mapstruct.Javadoc` annotation.
+
+This functionality could be relevant especially in situations where certain Javadoc standards need to be met or
+to deal with Javadoc validation constraints.
+
+The `@Javadoc` annotation defines attributes for the different Javadoc elements.
+
+Consider the following example:
+
+.Javadoc annotation example
+====
+[source, java, linenums]
+[subs="verbatim,attributes"]
+----
+@Mapper
+@Javadoc(
+    value = "This is the description",
+    authors = { "author1", "author2" },
+    deprecated = "Use {@link OtherMapper} instead",
+    since = "0.1"
+)
+public interface MyAnnotatedWithJavadocMapper {
+    //...
+}
+----
+====
+
+.Javadoc annotated generated mapper
+====
+[source, java, linenums]
+[subs="verbatim,attributes"]
+----
+/**
+* This is the description
+*
+* @author author1
+* @author author2
+*
+* @deprecated Use {@link OtherMapper} instead
+* @since 0.1
+*/
+public class MyAnnotatedWithJavadocMapperImpl implements MyAnnotatedWithJavadocMapper {
+    //...
+}
+----
+====
+
+The entire Javadoc comment block can be provided directly as well.
+
+.Javadoc annotation example with the entire Javadoc comment block provided directly
+====
+[source, java, linenums]
+[subs="verbatim,attributes"]
+----
+@Mapper
+@Javadoc(
+    "This is the description\n"
+  + "\n"
+  + "@author author1\n"
+  + "@author author2\n"
+  + "\n"
+  + "@deprecated Use {@link OtherMapper} instead\n"
+  + "@since 0.1\n"
+)
+public interface MyAnnotatedWithJavadocMapper {
+    //...
+}
+----
+====
+
+Or using Text blocks:
+
+.Javadoc annotation example with the entire Javadoc comment block provided directly using Text blocks
+====
+[source, java, linenums]
+[subs="verbatim,attributes"]
+----
+@Mapper
+@Javadoc(
+    """
+    This is the description
+
+    @author author1
+    @author author2
+
+    @deprecated Use {@link OtherMapper} instead
+    @since 0.1
+    """
+)
+public interface MyAnnotatedWithJavadocMapper {
+    //...
+}
+----
+====
diff --git a/processor/src/main/java/org/mapstruct/ap/internal/gem/GemGenerator.java b/processor/src/main/java/org/mapstruct/ap/internal/gem/GemGenerator.java
@@ -21,6 +21,7 @@
 import org.mapstruct.InheritConfiguration;
 import org.mapstruct.InheritInverseConfiguration;
 import org.mapstruct.IterableMapping;
+import org.mapstruct.Javadoc;
 import org.mapstruct.MapMapping;
 import org.mapstruct.Mapper;
 import org.mapstruct.MapperConfig;
@@ -75,6 +76,7 @@
 @GemDefinition(Context.class)
 @GemDefinition(Builder.class)
 @GemDefinition(Condition.class)
+@GemDefinition(Javadoc.class)
 
 @GemDefinition(MappingControl.class)
 @GemDefinition(MappingControls.class)

diff --git a/processor/src/main/java/org/mapstruct/ap/internal/model/GeneratedType.java b/processor/src/main/java/org/mapstruct/ap/internal/model/GeneratedType.java
@@ -253,6 +253,10 @@ public void removeConstructor() {
         constructor = null;
     }
 
+    public Javadoc getJavadoc() {
+        return null;
+    }
+
     protected void addIfImportRequired(Collection<Type> collection, Type typeToAdd) {
         if ( typeToAdd == null ) {
             return;

diff --git a/processor/src/main/java/org/mapstruct/ap/internal/model/Javadoc.java b/processor/src/main/java/org/mapstruct/ap/internal/model/Javadoc.java
@@ -0,0 +1,92 @@
+/*
+ * Copyright MapStruct Authors.
+ *
+ * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+package org.mapstruct.ap.internal.model;
+
+import org.mapstruct.ap.internal.model.common.ModelElement;
+import org.mapstruct.ap.internal.model.common.Type;
+
+import java.util.Collections;
+import java.util.List;
+import java.util.Set;
+
+/**
+ * Represents the javadoc information that should be generated for a {@link Mapper}.
+ *
+ * @author Jose Carlos Campanero Ortiz
+ */
+public class Javadoc extends ModelElement {
+
+    public static class Builder {
+
+        private String value;
+        private List<String> authors;
+        private String deprecated;
+        private String since;
+
+        public Builder value(String value) {
+            this.value = value;
+            return this;
+        }
+
+        public Builder authors(List authors) {
+            this.authors = authors;
+            return this;
+        }
+
+        public Builder deprecated(String deprecated) {
+            this.deprecated = deprecated;
+            return this;
+        }
+
+        public Builder since(String since) {
+            this.since = since;
+            return this;
+        }
+
+        public Javadoc build() {
+            return new Javadoc(
+                    value,
+                    authors,
+                    deprecated,
+                    since
+            );
+        }
+    }
+
+    private final String value;
+    private final List<String> authors;
+    private final String deprecated;
+    private final String since;
+
+    private Javadoc(String value, List<String> authors, String deprecated, String since) {
+        this.value = value;
+        this.authors = authors != null ? Collections.unmodifiableList( authors ) : Collections.emptyList();
+        this.deprecated = deprecated;
+        this.since = since;
+    }
+
+    public String getValue() {
+        return value;
+    }
+
+    public List<String> getAuthors() {
+        return authors;
+    }
+
+    public String getDeprecated() {
+        return deprecated;
+    }
+
+    public String getSince() {
+        return since;
+    }
+
+    @Override
+    public Set<Type> getImportTypes() {
+        return Collections.emptySet();
+    }
+
+}