From 286506a90b9322061c70e93b09c73435e929463c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Carlos=20Campanero=20Ortiz?= Date: Tue, 28 Mar 2023 23:49:53 +0200 Subject: [PATCH 01/19] #2987 Support for Javadoc in generated Mapper initial implementation --- core/src/main/java/org/mapstruct/Javadoc.java | 20 ++++ .../ap/internal/gem/GemGenerator.java | 2 + .../ap/internal/model/GeneratedType.java | 8 ++ .../mapstruct/ap/internal/model/Javadoc.java | 105 ++++++++++++++++++ .../mapstruct/ap/internal/model/Mapper.java | 19 +++- .../processor/MapperCreationProcessor.java | 20 ++++ .../ap/internal/model/GeneratedType.ftl | 3 + .../mapstruct/ap/internal/model/Javadoc.ftl | 25 +++++ .../JavadocAnnotatedWithAttributesMapper.java | 21 ++++ .../JavadocAnnotatedWithValueMapper.java | 22 ++++ .../ap/test/javadoc/JavadocTest.java | 49 ++++++++ 11 files changed, 292 insertions(+), 2 deletions(-) create mode 100644 core/src/main/java/org/mapstruct/Javadoc.java create mode 100644 processor/src/main/java/org/mapstruct/ap/internal/model/Javadoc.java create mode 100644 processor/src/main/resources/org/mapstruct/ap/internal/model/Javadoc.ftl create mode 100644 processor/src/test/java/org/mapstruct/ap/test/javadoc/JavadocAnnotatedWithAttributesMapper.java create mode 100644 processor/src/test/java/org/mapstruct/ap/test/javadoc/JavadocAnnotatedWithValueMapper.java create mode 100644 processor/src/test/java/org/mapstruct/ap/test/javadoc/JavadocTest.java diff --git a/core/src/main/java/org/mapstruct/Javadoc.java b/core/src/main/java/org/mapstruct/Javadoc.java new file mode 100644 index 0000000000..90baeccbcc --- /dev/null +++ b/core/src/main/java/org/mapstruct/Javadoc.java @@ -0,0 +1,20 @@ +/* + * 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; + +@Target(ElementType.TYPE) +@Retention(RetentionPolicy.CLASS) +public @interface Javadoc { + String value() default ""; + String[] authors() default {}; + String deprecated() default ""; + String since() default ""; +} 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 index 5caea8a008..9ac13184cd 100644 --- 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 index df6ed9b2b1..70ba4eb97c 100644 --- 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,14 @@ public void removeConstructor() { constructor = null; } + public boolean hasJavadoc() { + return getJavadoc() != null; + } + + public Javadoc getJavadoc() { + return null; + } + protected void addIfImportRequired(Collection 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 new file mode 100644 index 0000000000..a5a54c9768 --- /dev/null +++ b/processor/src/main/java/org/mapstruct/ap/internal/model/Javadoc.java @@ -0,0 +1,105 @@ +/* + * 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 org.mapstruct.ap.internal.util.Strings; + +import java.util.Collections; +import java.util.List; +import java.util.Optional; +import java.util.Set; + +public class Javadoc extends ModelElement { + + public static class Builder { + + private String value; + private List 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 authors; + private final String deprecated; + private final String since; + + private Javadoc(String value, List authors, String deprecated, String since) { + this.value = value; + this.authors = authors; + this.deprecated = deprecated; + this.since = since; + } + + public String getValue() { + return value; + } + + public boolean hasAuthors() { + return authors != null && !authors.isEmpty(); + } + + public List getAuthors() { + return Collections.unmodifiableList( + Optional + .ofNullable( authors ) + .orElse( Collections.emptyList() ) + ); + } + + public boolean hasDeprecated() { + return !Strings.isEmpty( deprecated ); + } + + public String getDeprecated() { + return deprecated; + } + + public boolean hasSince() { + return !Strings.isEmpty( since ); + } + + public String getSince() { + return since; + } + + @Override + public Set getImportTypes() { + return Collections.emptySet(); + } + +} diff --git a/processor/src/main/java/org/mapstruct/ap/internal/model/Mapper.java b/processor/src/main/java/org/mapstruct/ap/internal/model/Mapper.java index 9b7729e8fa..750755f65c 100644 --- a/processor/src/main/java/org/mapstruct/ap/internal/model/Mapper.java +++ b/processor/src/main/java/org/mapstruct/ap/internal/model/Mapper.java @@ -43,6 +43,7 @@ public static class Builder extends GeneratedTypeBuilder { private boolean customPackage; private boolean suppressGeneratorTimestamp; private Set customAnnotations; + private Javadoc javadoc; public Builder() { super( Builder.class ); @@ -90,6 +91,11 @@ public Builder suppressGeneratorTimestamp(boolean suppressGeneratorTimestamp) { return this; } + public Builder javadoc(Javadoc javadoc) { + this.javadoc = javadoc; + return this; + } + public Mapper build() { String implementationName = implName.replace( CLASS_NAME_PLACEHOLDER, getFlatName( element ) ) + ( decorator == null ? "" : "_" ); @@ -119,7 +125,8 @@ public Mapper build() { fields, constructor, decorator, - extraImportedTypes + extraImportedTypes, + javadoc ); } @@ -128,6 +135,7 @@ public Mapper build() { private final boolean customPackage; private final boolean customImplName; private Decorator decorator; + private Javadoc javadoc; @SuppressWarnings( "checkstyle:parameternumber" ) private Mapper(TypeFactory typeFactory, String packageName, String name, @@ -136,7 +144,7 @@ private Mapper(TypeFactory typeFactory, String packageName, String name, List methods, Options options, VersionInformation versionInformation, boolean suppressGeneratorTimestamp, Accessibility accessibility, List fields, Constructor constructor, - Decorator decorator, SortedSet extraImportedTypes ) { + Decorator decorator, SortedSet extraImportedTypes, Javadoc javadoc ) { super( typeFactory, @@ -157,6 +165,8 @@ private Mapper(TypeFactory typeFactory, String packageName, String name, customAnnotations.forEach( this::addAnnotation ); this.decorator = decorator; + + this.javadoc = javadoc; } public Decorator getDecorator() { @@ -171,6 +181,11 @@ public boolean hasCustomImplementation() { return customImplName || customPackage; } + @Override + public Javadoc getJavadoc() { + return javadoc; + } + @Override protected String getTemplateName() { return getTemplateNameForClass( GeneratedType.class ); diff --git a/processor/src/main/java/org/mapstruct/ap/internal/processor/MapperCreationProcessor.java b/processor/src/main/java/org/mapstruct/ap/internal/processor/MapperCreationProcessor.java index b69ba388b0..29d0a3daa5 100644 --- a/processor/src/main/java/org/mapstruct/ap/internal/processor/MapperCreationProcessor.java +++ b/processor/src/main/java/org/mapstruct/ap/internal/processor/MapperCreationProcessor.java @@ -28,6 +28,7 @@ import org.mapstruct.ap.internal.gem.DecoratedWithGem; import org.mapstruct.ap.internal.gem.InheritConfigurationGem; import org.mapstruct.ap.internal.gem.InheritInverseConfigurationGem; +import org.mapstruct.ap.internal.gem.JavadocGem; import org.mapstruct.ap.internal.gem.MapperGem; import org.mapstruct.ap.internal.gem.MappingInheritanceStrategyGem; import org.mapstruct.ap.internal.gem.NullValueMappingStrategyGem; @@ -40,6 +41,7 @@ import org.mapstruct.ap.internal.model.DelegatingMethod; import org.mapstruct.ap.internal.model.Field; import org.mapstruct.ap.internal.model.IterableMappingMethod; +import org.mapstruct.ap.internal.model.Javadoc; import org.mapstruct.ap.internal.model.MapMappingMethod; import org.mapstruct.ap.internal.model.Mapper; import org.mapstruct.ap.internal.model.MapperReference; @@ -212,6 +214,7 @@ private Mapper getMapper(TypeElement element, MapperOptions mapperOptions, List< .implPackage( mapperOptions.implementationPackage() ) .suppressGeneratorTimestamp( mapperOptions.suppressTimestampInGenerated() ) .additionalAnnotations( additionalAnnotationsBuilder.getProcessedAnnotations( element ) ) + .javadoc( getJavadoc( element ) ) .build(); if ( !mappingContext.getForgedMethodsUnderCreation().isEmpty() ) { @@ -441,6 +444,23 @@ else if ( method.isStreamMapping() ) { return mappingMethods; } + private Javadoc getJavadoc(TypeElement element) { + JavadocGem javadocGem = JavadocGem.instanceOn( element ); + + if ( javadocGem == null ) { + return null; + } + + Javadoc javadoc = new Javadoc.Builder() + .value( javadocGem.value().getValue() ) + .authors( javadocGem.authors().getValue() ) + .deprecated( javadocGem.deprecated().getValue() ) + .since( javadocGem.since().getValue() ) + .build(); + + return javadoc; + } + private Type getUserDesiredReturnType(SourceMethod method) { SelectionParameters selectionParameters = method.getOptions().getBeanMapping().getSelectionParameters(); if ( selectionParameters != null && selectionParameters.getResultType() != null ) { diff --git a/processor/src/main/resources/org/mapstruct/ap/internal/model/GeneratedType.ftl b/processor/src/main/resources/org/mapstruct/ap/internal/model/GeneratedType.ftl index 4981882403..cb6a6f2dc4 100644 --- a/processor/src/main/resources/org/mapstruct/ap/internal/model/GeneratedType.ftl +++ b/processor/src/main/resources/org/mapstruct/ap/internal/model/GeneratedType.ftl @@ -14,6 +14,9 @@ package ${packageName}; import ${importedType}; +<#if hasJavadoc()> +<#nt><@includeModel object=javadoc/> + <#if !generatedTypeAvailable>/* @Generated( value = "org.mapstruct.ap.MappingProcessor"<#if suppressGeneratorTimestamp == false>, diff --git a/processor/src/main/resources/org/mapstruct/ap/internal/model/Javadoc.ftl b/processor/src/main/resources/org/mapstruct/ap/internal/model/Javadoc.ftl new file mode 100644 index 0000000000..a144b6dae3 --- /dev/null +++ b/processor/src/main/resources/org/mapstruct/ap/internal/model/Javadoc.ftl @@ -0,0 +1,25 @@ +<#-- + + Copyright MapStruct Authors. + + Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0 + +--> +<#-- @ftlvariable name="" type="org.mapstruct.ap.internal.model.Javadoc" --> +/** +<#list value?split("\n") as line><#nt>*<#if line?has_content> ${line?trim} + +<#if hasAuthors()> +* +<#list authors as author> <#nt>* @author ${author?trim} + + +<#if hasDeprecated()> +* +<#nt>* @deprecated ${deprecated?trim} + +<#if hasSince()> +* +<#nt>* @since ${since?trim} + +<#nt> */ \ No newline at end of file diff --git a/processor/src/test/java/org/mapstruct/ap/test/javadoc/JavadocAnnotatedWithAttributesMapper.java b/processor/src/test/java/org/mapstruct/ap/test/javadoc/JavadocAnnotatedWithAttributesMapper.java new file mode 100644 index 0000000000..eb6285ff13 --- /dev/null +++ b/processor/src/test/java/org/mapstruct/ap/test/javadoc/JavadocAnnotatedWithAttributesMapper.java @@ -0,0 +1,21 @@ +/* + * 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.test.javadoc; + +import org.mapstruct.Javadoc; +import org.mapstruct.Mapper; + +@Mapper +@Javadoc( + value = "This is the description", + authors = { "author1", "author2" }, + deprecated = "Use {@link OtherMapper} instead", + since = "0.1" +) +@Deprecated +public interface JavadocAnnotatedWithAttributesMapper { + +} diff --git a/processor/src/test/java/org/mapstruct/ap/test/javadoc/JavadocAnnotatedWithValueMapper.java b/processor/src/test/java/org/mapstruct/ap/test/javadoc/JavadocAnnotatedWithValueMapper.java new file mode 100644 index 0000000000..150d7e5f76 --- /dev/null +++ b/processor/src/test/java/org/mapstruct/ap/test/javadoc/JavadocAnnotatedWithValueMapper.java @@ -0,0 +1,22 @@ +/* + * 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.test.javadoc; + +import org.mapstruct.Javadoc; +import org.mapstruct.Mapper; + +@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") +@Deprecated +public interface JavadocAnnotatedWithValueMapper { + +} diff --git a/processor/src/test/java/org/mapstruct/ap/test/javadoc/JavadocTest.java b/processor/src/test/java/org/mapstruct/ap/test/javadoc/JavadocTest.java new file mode 100644 index 0000000000..3739f052ac --- /dev/null +++ b/processor/src/test/java/org/mapstruct/ap/test/javadoc/JavadocTest.java @@ -0,0 +1,49 @@ +/* + * 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.test.javadoc; + +import org.assertj.core.api.AbstractCharSequenceAssert; +import org.junit.jupiter.api.extension.RegisterExtension; +import org.mapstruct.ap.test.annotatewith.AnnotateWithEnum; +import org.mapstruct.ap.testutil.IssueKey; +import org.mapstruct.ap.testutil.ProcessorTest; +import org.mapstruct.ap.testutil.WithClasses; +import org.mapstruct.ap.testutil.runner.GeneratedSource; + +/** + * @author Jose Carlos Campanero Ortiz + */ +@IssueKey("2987") +@WithClasses(AnnotateWithEnum.class) +public class JavadocTest { + + @RegisterExtension + final GeneratedSource generatedSource = new GeneratedSource(); + + @ProcessorTest + @WithClasses( { JavadocAnnotatedWithValueMapper.class } ) + public void javadocAnnotatedWithValueMapper() { + AbstractCharSequenceAssert content = generatedSource + .forMapper( JavadocAnnotatedWithValueMapper.class ) + .content(); + content + .contains( "This is the description" ); + } + + @ProcessorTest + @WithClasses( { JavadocAnnotatedWithAttributesMapper.class } ) + public void javadocAnnotatedWithAttributesMapper() { + AbstractCharSequenceAssert content = generatedSource + .forMapper( JavadocAnnotatedWithAttributesMapper.class ) + .content(); + content + .contains( "This is the description" ) + .contains( "@author author1" ) + .contains( "@author author2" ) + .contains( "@deprecated Use {@link OtherMapper} instead" ) + .contains( "@since 0.1" ); + } +} From de2802252d56063745679e9f76d87da17fdbefb0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Carlos=20Campanero=20Ortiz?= Date: Sun, 23 Apr 2023 00:37:00 +0200 Subject: [PATCH 02/19] Change Javadoc annotation retention policy type --- core/src/main/java/org/mapstruct/Javadoc.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/core/src/main/java/org/mapstruct/Javadoc.java b/core/src/main/java/org/mapstruct/Javadoc.java index 90baeccbcc..2f752ff241 100644 --- a/core/src/main/java/org/mapstruct/Javadoc.java +++ b/core/src/main/java/org/mapstruct/Javadoc.java @@ -11,7 +11,7 @@ import java.lang.annotation.Target; @Target(ElementType.TYPE) -@Retention(RetentionPolicy.CLASS) +@Retention(RetentionPolicy.SOURCE) public @interface Javadoc { String value() default ""; String[] authors() default {}; From baad101be8155ac0a59d63c7331ca6582700e04c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Carlos=20Campanero=20Ortiz?= Date: Sun, 23 Apr 2023 00:38:40 +0200 Subject: [PATCH 03/19] Provide Javadoc documentation for the Javadoc annotation --- core/src/main/java/org/mapstruct/Javadoc.java | 98 ++++++++++++++++++- 1 file changed, 97 insertions(+), 1 deletion(-) diff --git a/core/src/main/java/org/mapstruct/Javadoc.java b/core/src/main/java/org/mapstruct/Javadoc.java index 2f752ff241..8239174834 100644 --- a/core/src/main/java/org/mapstruct/Javadoc.java +++ b/core/src/main/java/org/mapstruct/Javadoc.java @@ -10,11 +10,107 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; +/** + * Allows the definition of Javadoc comments in the MapStruct Mapper generated class. + * + * + *

The annotation provides support for the usual Javadoc comments elements by defining analogous attributes.

+ * + * + *

Please, note that at least one of these attributes must be specified.

+ * + *

+ * For instance, the following definition; + *

+ * 

+ * @Javadoc(
+ *     value = "This is the description",
+ *     authors = { "author1", "author2" },
+ *     deprecated = "Use {@link OtherMapper} instead",
+ *     since = "0.1"
+ * )
+ *
+ * + *

+ * will generate: + *

+ * + * 

+ * /**
+ * * This is the description
+ * *
+ * * @author author1
+ * * @author author2
+ * *
+ * * @deprecated Use {@link OtherMapper} instead
+ * * @since 0.1
+ * */
+ *
+ * + *

+ * The whole Javadoc comment block can be passed directly: + *

+ * 

+ * @Javadoc("This is the description\n"
+ *            + "\n"
+ *            + "@author author1\n"
+ *            + "@author author2\n"
+ *            + "\n"
+ *            + "@deprecated Use {@link OtherMapper} instead\n"
+ *            + "@since 0.1\n"
+ * )
+ *
+ * + * 

+ * // or using Text Blocks
+ * @Javadoc(
+ *     """
+ *     This is the description
+ *
+ *     @author author1
+ *     @author author2
+ *
+ *     @deprecated Use {@link OtherMapper} instead
+ *     @since 0.1
+ *     """
+ * )
+ *
+ */ @Target(ElementType.TYPE) @Retention(RetentionPolicy.SOURCE) public @interface Javadoc { + /** + * Main Javadoc comment text block. + * + * @return Main Javadoc comment text block. + */ String value() default ""; - String[] authors() default {}; + + /** + * List of authors of the code that it is being documented. + * + * It will generated a list of the Javadoc tool comment element @author + * with the different values and in the order provided. + * + * @return List of authors of the functionality being documented. + */ + String[] authors() default { }; + + /** + * Specifies that the functionality that is being documented is deprecated. + * + * Corresponds to the @deprecated 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. + * + * Corresponds to the @since Javadoc tool comment element. + * + * @return Version since the functionality is available + */ String since() default ""; } From c3fa86755fe375a0e14e04ba6d69a5e81c7b33e5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Carlos=20Campanero=20Ortiz?= Date: Sun, 23 Apr 2023 00:40:33 +0200 Subject: [PATCH 04/19] Improve Javadoc Freemarker related templates --- .../ap/internal/model/GeneratedType.java | 4 ---- .../mapstruct/ap/internal/model/Javadoc.java | 22 ++----------------- .../ap/internal/model/GeneratedType.ftl | 4 +--- .../mapstruct/ap/internal/model/Javadoc.ftl | 6 ++--- 4 files changed, 6 insertions(+), 30 deletions(-) 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 index 70ba4eb97c..8348ecd84b 100644 --- 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,10 +253,6 @@ public void removeConstructor() { constructor = null; } - public boolean hasJavadoc() { - return getJavadoc() != null; - } - public Javadoc getJavadoc() { return null; } 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 index a5a54c9768..d6b71b8a13 100644 --- a/processor/src/main/java/org/mapstruct/ap/internal/model/Javadoc.java +++ b/processor/src/main/java/org/mapstruct/ap/internal/model/Javadoc.java @@ -7,11 +7,9 @@ import org.mapstruct.ap.internal.model.common.ModelElement; import org.mapstruct.ap.internal.model.common.Type; -import org.mapstruct.ap.internal.util.Strings; import java.util.Collections; import java.util.List; -import java.util.Optional; import java.util.Set; public class Javadoc extends ModelElement { @@ -60,7 +58,7 @@ public Javadoc build() { private Javadoc(String value, List authors, String deprecated, String since) { this.value = value; - this.authors = authors; + this.authors = authors != null ? Collections.unmodifiableList( authors ) : Collections.emptyList(); this.deprecated = deprecated; this.since = since; } @@ -69,30 +67,14 @@ public String getValue() { return value; } - public boolean hasAuthors() { - return authors != null && !authors.isEmpty(); - } - public List getAuthors() { - return Collections.unmodifiableList( - Optional - .ofNullable( authors ) - .orElse( Collections.emptyList() ) - ); - } - - public boolean hasDeprecated() { - return !Strings.isEmpty( deprecated ); + return authors; } public String getDeprecated() { return deprecated; } - public boolean hasSince() { - return !Strings.isEmpty( since ); - } - public String getSince() { return since; } diff --git a/processor/src/main/resources/org/mapstruct/ap/internal/model/GeneratedType.ftl b/processor/src/main/resources/org/mapstruct/ap/internal/model/GeneratedType.ftl index cb6a6f2dc4..c65b3e5f85 100644 --- a/processor/src/main/resources/org/mapstruct/ap/internal/model/GeneratedType.ftl +++ b/processor/src/main/resources/org/mapstruct/ap/internal/model/GeneratedType.ftl @@ -14,9 +14,7 @@ package ${packageName}; import ${importedType}; -<#if hasJavadoc()> -<#nt><@includeModel object=javadoc/> - +<#if javadoc??><#nt><@includeModel object=javadoc/> <#if !generatedTypeAvailable>/* @Generated( value = "org.mapstruct.ap.MappingProcessor"<#if suppressGeneratorTimestamp == false>, diff --git a/processor/src/main/resources/org/mapstruct/ap/internal/model/Javadoc.ftl b/processor/src/main/resources/org/mapstruct/ap/internal/model/Javadoc.ftl index a144b6dae3..89ac57b9ef 100644 --- a/processor/src/main/resources/org/mapstruct/ap/internal/model/Javadoc.ftl +++ b/processor/src/main/resources/org/mapstruct/ap/internal/model/Javadoc.ftl @@ -9,16 +9,16 @@ /** <#list value?split("\n") as line><#nt>*<#if line?has_content> ${line?trim} -<#if hasAuthors()> +<#if !authors.isEmpty()> * <#list authors as author> <#nt>* @author ${author?trim} -<#if hasDeprecated()> +<#if deprecated?has_content> * <#nt>* @deprecated ${deprecated?trim} -<#if hasSince()> +<#if since?has_content> * <#nt>* @since ${since?trim} From 0bf3043ebb43506547f968bb0344a69cc9631f6d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Carlos=20Campanero=20Ortiz?= Date: Sun, 23 Apr 2023 00:41:25 +0200 Subject: [PATCH 05/19] Make javadoc instance field final in Mapper. --- .../src/main/java/org/mapstruct/ap/internal/model/Mapper.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/processor/src/main/java/org/mapstruct/ap/internal/model/Mapper.java b/processor/src/main/java/org/mapstruct/ap/internal/model/Mapper.java index 750755f65c..cd092ca4f4 100644 --- a/processor/src/main/java/org/mapstruct/ap/internal/model/Mapper.java +++ b/processor/src/main/java/org/mapstruct/ap/internal/model/Mapper.java @@ -135,7 +135,7 @@ public Mapper build() { private final boolean customPackage; private final boolean customImplName; private Decorator decorator; - private Javadoc javadoc; + private final Javadoc javadoc; @SuppressWarnings( "checkstyle:parameternumber" ) private Mapper(TypeFactory typeFactory, String packageName, String name, From 1c796391c707bf1e059646aaa5f8c65babd77f7a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Carlos=20Campanero=20Ortiz?= Date: Sun, 23 Apr 2023 00:42:06 +0200 Subject: [PATCH 06/19] Remove obsolete test reference --- .../test/java/org/mapstruct/ap/test/javadoc/JavadocTest.java | 2 -- 1 file changed, 2 deletions(-) diff --git a/processor/src/test/java/org/mapstruct/ap/test/javadoc/JavadocTest.java b/processor/src/test/java/org/mapstruct/ap/test/javadoc/JavadocTest.java index 3739f052ac..5e819afb04 100644 --- a/processor/src/test/java/org/mapstruct/ap/test/javadoc/JavadocTest.java +++ b/processor/src/test/java/org/mapstruct/ap/test/javadoc/JavadocTest.java @@ -7,7 +7,6 @@ import org.assertj.core.api.AbstractCharSequenceAssert; import org.junit.jupiter.api.extension.RegisterExtension; -import org.mapstruct.ap.test.annotatewith.AnnotateWithEnum; import org.mapstruct.ap.testutil.IssueKey; import org.mapstruct.ap.testutil.ProcessorTest; import org.mapstruct.ap.testutil.WithClasses; @@ -17,7 +16,6 @@ * @author Jose Carlos Campanero Ortiz */ @IssueKey("2987") -@WithClasses(AnnotateWithEnum.class) public class JavadocTest { @RegisterExtension From 1571249345310c15267c27a0c0006a94b11c351a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Carlos=20Campanero=20Ortiz?= Date: Sun, 23 Apr 2023 00:43:13 +0200 Subject: [PATCH 07/19] Check that at least one attribute is provided for @Javadoc --- .../internal/processor/MapperCreationProcessor.java | 13 ++++++++++++- .../org/mapstruct/ap/internal/util/Message.java | 2 ++ 2 files changed, 14 insertions(+), 1 deletion(-) diff --git a/processor/src/main/java/org/mapstruct/ap/internal/processor/MapperCreationProcessor.java b/processor/src/main/java/org/mapstruct/ap/internal/processor/MapperCreationProcessor.java index 29d0a3daa5..6a72f90ac8 100644 --- a/processor/src/main/java/org/mapstruct/ap/internal/processor/MapperCreationProcessor.java +++ b/processor/src/main/java/org/mapstruct/ap/internal/processor/MapperCreationProcessor.java @@ -447,7 +447,7 @@ else if ( method.isStreamMapping() ) { private Javadoc getJavadoc(TypeElement element) { JavadocGem javadocGem = JavadocGem.instanceOn( element ); - if ( javadocGem == null ) { + if ( javadocGem == null || !isConsistent( javadocGem, element, messager ) ) { return null; } @@ -830,4 +830,15 @@ private void reportErrorWhenNonMatchingName(SourceMethod onlyCandidate, SourceMe onlyCandidate.getName() ); } + + private boolean isConsistent( JavadocGem gem, TypeElement element, FormattingMessager messager ) { + if ( !gem.value().hasValue() + && !gem.authors().hasValue() + && !gem.deprecated().hasValue() + && !gem.since().hasValue() ) { + messager.printMessage( element, Message.JAVADOC_NO_ELEMENTS ); + return false; + } + return true; + } } diff --git a/processor/src/main/java/org/mapstruct/ap/internal/util/Message.java b/processor/src/main/java/org/mapstruct/ap/internal/util/Message.java index 29600489fb..a2c9caacdc 100644 --- a/processor/src/main/java/org/mapstruct/ap/internal/util/Message.java +++ b/processor/src/main/java/org/mapstruct/ap/internal/util/Message.java @@ -130,6 +130,8 @@ public enum Message { DECORATOR_NO_SUBTYPE( "Specified decorator type is no subtype of the annotated mapper type." ), DECORATOR_CONSTRUCTOR( "Specified decorator type has no default constructor nor a constructor with a single parameter accepting the decorated mapper type." ), + JAVADOC_NO_ELEMENTS( "'value', 'authors', 'deprecated' and 'since' are undefined in @Javadoc, define at least one of them.\"." ), + GENERAL_CANNOT_IMPLEMENT_PRIVATE_MAPPER("Cannot create an implementation for mapper %s, because it is a private %s."), GENERAL_NO_IMPLEMENTATION( "No implementation type is registered for return type %s." ), GENERAL_ABSTRACT_RETURN_TYPE( "The return type %s is an abstract class or interface. Provide a non abstract / non interface result type or a factory method." ), From 702eee50b74ebb9e7b4f0c6e143ad52fedcdeab9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Carlos=20Campanero=20Ortiz?= Date: Wed, 26 Apr 2023 00:33:41 +0200 Subject: [PATCH 08/19] Add reference to @Javadoc annotation in comments. --- core/src/main/java/org/mapstruct/Mapper.java | 1 + 1 file changed, 1 insertion(+) diff --git a/core/src/main/java/org/mapstruct/Mapper.java b/core/src/main/java/org/mapstruct/Mapper.java index 60725cc441..8a6f48dad9 100644 --- a/core/src/main/java/org/mapstruct/Mapper.java +++ b/core/src/main/java/org/mapstruct/Mapper.java @@ -74,6 +74,7 @@ * * * @author Gunnar Morling + * @see Javadoc */ @Target(ElementType.TYPE) @Retention(RetentionPolicy.CLASS) From d4d2184c1fc088f6db3f1b1f52981fa71bd63fec Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Carlos=20Campanero=20Ortiz?= Date: Wed, 26 Apr 2023 00:34:30 +0200 Subject: [PATCH 09/19] Provide some comments for Javadoc model. --- .../main/java/org/mapstruct/ap/internal/model/Javadoc.java | 5 +++++ 1 file changed, 5 insertions(+) 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 index d6b71b8a13..a1efc8c022 100644 --- a/processor/src/main/java/org/mapstruct/ap/internal/model/Javadoc.java +++ b/processor/src/main/java/org/mapstruct/ap/internal/model/Javadoc.java @@ -12,6 +12,11 @@ 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 { From 72b21170d3af80c35e01cd71d5d56dae300782c4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Carlos=20Campanero=20Ortiz?= Date: Wed, 26 Apr 2023 00:35:39 +0200 Subject: [PATCH 10/19] Provide information about AnotationMirror on empty Javadoc annotation. --- .../ap/internal/processor/MapperCreationProcessor.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/processor/src/main/java/org/mapstruct/ap/internal/processor/MapperCreationProcessor.java b/processor/src/main/java/org/mapstruct/ap/internal/processor/MapperCreationProcessor.java index 6a72f90ac8..24dd528f6b 100644 --- a/processor/src/main/java/org/mapstruct/ap/internal/processor/MapperCreationProcessor.java +++ b/processor/src/main/java/org/mapstruct/ap/internal/processor/MapperCreationProcessor.java @@ -836,7 +836,7 @@ private boolean isConsistent( JavadocGem gem, TypeElement element, FormattingMes && !gem.authors().hasValue() && !gem.deprecated().hasValue() && !gem.since().hasValue() ) { - messager.printMessage( element, Message.JAVADOC_NO_ELEMENTS ); + messager.printMessage( element, gem.mirror(), Message.JAVADOC_NO_ELEMENTS ); return false; } return true; From 041c974a1b30044e6c94ece6608eea5e56643831 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Carlos=20Campanero=20Ortiz?= Date: Wed, 26 Apr 2023 00:36:52 +0200 Subject: [PATCH 11/19] Remove trailing characters on JAVADOC_NO_ELEMENTS error message. --- .../src/main/java/org/mapstruct/ap/internal/util/Message.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/processor/src/main/java/org/mapstruct/ap/internal/util/Message.java b/processor/src/main/java/org/mapstruct/ap/internal/util/Message.java index a2c9caacdc..6f72f720f1 100644 --- a/processor/src/main/java/org/mapstruct/ap/internal/util/Message.java +++ b/processor/src/main/java/org/mapstruct/ap/internal/util/Message.java @@ -130,7 +130,7 @@ public enum Message { DECORATOR_NO_SUBTYPE( "Specified decorator type is no subtype of the annotated mapper type." ), DECORATOR_CONSTRUCTOR( "Specified decorator type has no default constructor nor a constructor with a single parameter accepting the decorated mapper type." ), - JAVADOC_NO_ELEMENTS( "'value', 'authors', 'deprecated' and 'since' are undefined in @Javadoc, define at least one of them.\"." ), + JAVADOC_NO_ELEMENTS( "'value', 'authors', 'deprecated' and 'since' are undefined in @Javadoc, define at least one of them." ), GENERAL_CANNOT_IMPLEMENT_PRIVATE_MAPPER("Cannot create an implementation for mapper %s, because it is a private %s."), GENERAL_NO_IMPLEMENTATION( "No implementation type is registered for return type %s." ), From 57fce097c698e7dc0bdb5e874b64d899a394b009 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Carlos=20Campanero=20Ortiz?= Date: Wed, 26 Apr 2023 00:40:21 +0200 Subject: [PATCH 12/19] Add falling test for empty javadoc annotation error. --- .../erroneous/EmptyJavadocMapper.java | 17 +++++++++ .../erroneous/ErroneousJavadocTest.java | 37 +++++++++++++++++++ 2 files changed, 54 insertions(+) create mode 100644 processor/src/test/java/org/mapstruct/ap/test/collection/erroneous/EmptyJavadocMapper.java create mode 100644 processor/src/test/java/org/mapstruct/ap/test/collection/erroneous/ErroneousJavadocTest.java diff --git a/processor/src/test/java/org/mapstruct/ap/test/collection/erroneous/EmptyJavadocMapper.java b/processor/src/test/java/org/mapstruct/ap/test/collection/erroneous/EmptyJavadocMapper.java new file mode 100644 index 0000000000..2848c1f622 --- /dev/null +++ b/processor/src/test/java/org/mapstruct/ap/test/collection/erroneous/EmptyJavadocMapper.java @@ -0,0 +1,17 @@ +/* + * 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.test.collection.erroneous; + +import org.mapstruct.Javadoc; +import org.mapstruct.Mapper; + +/** + * @author Jose Carlos Campanero Ortiz + */ +@Mapper +@Javadoc +public interface EmptyJavadocMapper { +} diff --git a/processor/src/test/java/org/mapstruct/ap/test/collection/erroneous/ErroneousJavadocTest.java b/processor/src/test/java/org/mapstruct/ap/test/collection/erroneous/ErroneousJavadocTest.java new file mode 100644 index 0000000000..0c02e7a023 --- /dev/null +++ b/processor/src/test/java/org/mapstruct/ap/test/collection/erroneous/ErroneousJavadocTest.java @@ -0,0 +1,37 @@ +/* + * 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.test.collection.erroneous; + +import javax.tools.Diagnostic.Kind; + +import org.mapstruct.ap.testutil.IssueKey; +import org.mapstruct.ap.testutil.ProcessorTest; +import org.mapstruct.ap.testutil.WithClasses; +import org.mapstruct.ap.testutil.compilation.annotation.CompilationResult; +import org.mapstruct.ap.testutil.compilation.annotation.Diagnostic; +import org.mapstruct.ap.testutil.compilation.annotation.ExpectedCompilationOutcome; + +/** + * @author Jose Carlos Campanero Ortiz + */ +public class ErroneousJavadocTest { + + @ProcessorTest + @IssueKey("2987") + @WithClasses({ EmptyJavadocMapper.class }) + @ExpectedCompilationOutcome( + value = CompilationResult.FAILED, + diagnostics = { + @Diagnostic(type = EmptyJavadocMapper.class, + kind = Kind.ERROR, + line = 10, + message = "'value', 'authors', 'deprecated' and 'since' are undefined in @Javadoc, " + + "define at least one of them.") + } + ) + public void shouldFailOnEmptyJavadocAnnotation() { + } +} From 9896924d2371dc4778991a99b1bf512330d48797 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Carlos=20Campanero=20Ortiz?= Date: Wed, 26 Apr 2023 01:01:19 +0200 Subject: [PATCH 13/19] Fix reported error line number Fix reported error line number, changed after license text inclusion. --- .../ap/test/collection/erroneous/ErroneousJavadocTest.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/processor/src/test/java/org/mapstruct/ap/test/collection/erroneous/ErroneousJavadocTest.java b/processor/src/test/java/org/mapstruct/ap/test/collection/erroneous/ErroneousJavadocTest.java index 0c02e7a023..f9d6c81d22 100644 --- a/processor/src/test/java/org/mapstruct/ap/test/collection/erroneous/ErroneousJavadocTest.java +++ b/processor/src/test/java/org/mapstruct/ap/test/collection/erroneous/ErroneousJavadocTest.java @@ -27,7 +27,7 @@ public class ErroneousJavadocTest { diagnostics = { @Diagnostic(type = EmptyJavadocMapper.class, kind = Kind.ERROR, - line = 10, + line = 15, message = "'value', 'authors', 'deprecated' and 'since' are undefined in @Javadoc, " + "define at least one of them.") } From ecef3462c15e7d9717bc00ade85609fb6bae9d1a Mon Sep 17 00:00:00 2001 From: Filip Hrisafov Date: Sun, 30 Apr 2023 16:07:26 +0200 Subject: [PATCH 14/19] Polishing Move Rename erroneous javadoc mapper and move it to the JavadocTest --- .../erroneous/ErroneousJavadocTest.java | 37 ------------------- .../ErroneousJavadocMapper.java} | 4 +- .../ap/test/javadoc/JavadocTest.java | 26 +++++++++++-- 3 files changed, 25 insertions(+), 42 deletions(-) delete mode 100644 processor/src/test/java/org/mapstruct/ap/test/collection/erroneous/ErroneousJavadocTest.java rename processor/src/test/java/org/mapstruct/ap/test/{collection/erroneous/EmptyJavadocMapper.java => javadoc/ErroneousJavadocMapper.java} (75%) diff --git a/processor/src/test/java/org/mapstruct/ap/test/collection/erroneous/ErroneousJavadocTest.java b/processor/src/test/java/org/mapstruct/ap/test/collection/erroneous/ErroneousJavadocTest.java deleted file mode 100644 index f9d6c81d22..0000000000 --- a/processor/src/test/java/org/mapstruct/ap/test/collection/erroneous/ErroneousJavadocTest.java +++ /dev/null @@ -1,37 +0,0 @@ -/* - * 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.test.collection.erroneous; - -import javax.tools.Diagnostic.Kind; - -import org.mapstruct.ap.testutil.IssueKey; -import org.mapstruct.ap.testutil.ProcessorTest; -import org.mapstruct.ap.testutil.WithClasses; -import org.mapstruct.ap.testutil.compilation.annotation.CompilationResult; -import org.mapstruct.ap.testutil.compilation.annotation.Diagnostic; -import org.mapstruct.ap.testutil.compilation.annotation.ExpectedCompilationOutcome; - -/** - * @author Jose Carlos Campanero Ortiz - */ -public class ErroneousJavadocTest { - - @ProcessorTest - @IssueKey("2987") - @WithClasses({ EmptyJavadocMapper.class }) - @ExpectedCompilationOutcome( - value = CompilationResult.FAILED, - diagnostics = { - @Diagnostic(type = EmptyJavadocMapper.class, - kind = Kind.ERROR, - line = 15, - message = "'value', 'authors', 'deprecated' and 'since' are undefined in @Javadoc, " - + "define at least one of them.") - } - ) - public void shouldFailOnEmptyJavadocAnnotation() { - } -} diff --git a/processor/src/test/java/org/mapstruct/ap/test/collection/erroneous/EmptyJavadocMapper.java b/processor/src/test/java/org/mapstruct/ap/test/javadoc/ErroneousJavadocMapper.java similarity index 75% rename from processor/src/test/java/org/mapstruct/ap/test/collection/erroneous/EmptyJavadocMapper.java rename to processor/src/test/java/org/mapstruct/ap/test/javadoc/ErroneousJavadocMapper.java index 2848c1f622..39f6da2890 100644 --- a/processor/src/test/java/org/mapstruct/ap/test/collection/erroneous/EmptyJavadocMapper.java +++ b/processor/src/test/java/org/mapstruct/ap/test/javadoc/ErroneousJavadocMapper.java @@ -3,7 +3,7 @@ * * Licensed under the Apache License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0 */ -package org.mapstruct.ap.test.collection.erroneous; +package org.mapstruct.ap.test.javadoc; import org.mapstruct.Javadoc; import org.mapstruct.Mapper; @@ -13,5 +13,5 @@ */ @Mapper @Javadoc -public interface EmptyJavadocMapper { +public interface ErroneousJavadocMapper { } diff --git a/processor/src/test/java/org/mapstruct/ap/test/javadoc/JavadocTest.java b/processor/src/test/java/org/mapstruct/ap/test/javadoc/JavadocTest.java index 5e819afb04..a34319eba1 100644 --- a/processor/src/test/java/org/mapstruct/ap/test/javadoc/JavadocTest.java +++ b/processor/src/test/java/org/mapstruct/ap/test/javadoc/JavadocTest.java @@ -10,20 +10,23 @@ import org.mapstruct.ap.testutil.IssueKey; import org.mapstruct.ap.testutil.ProcessorTest; import org.mapstruct.ap.testutil.WithClasses; +import org.mapstruct.ap.testutil.compilation.annotation.CompilationResult; +import org.mapstruct.ap.testutil.compilation.annotation.Diagnostic; +import org.mapstruct.ap.testutil.compilation.annotation.ExpectedCompilationOutcome; import org.mapstruct.ap.testutil.runner.GeneratedSource; /** * @author Jose Carlos Campanero Ortiz */ @IssueKey("2987") -public class JavadocTest { +class JavadocTest { @RegisterExtension final GeneratedSource generatedSource = new GeneratedSource(); @ProcessorTest @WithClasses( { JavadocAnnotatedWithValueMapper.class } ) - public void javadocAnnotatedWithValueMapper() { + void javadocAnnotatedWithValueMapper() { AbstractCharSequenceAssert content = generatedSource .forMapper( JavadocAnnotatedWithValueMapper.class ) .content(); @@ -33,7 +36,7 @@ public void javadocAnnotatedWithValueMapper() { @ProcessorTest @WithClasses( { JavadocAnnotatedWithAttributesMapper.class } ) - public void javadocAnnotatedWithAttributesMapper() { + void javadocAnnotatedWithAttributesMapper() { AbstractCharSequenceAssert content = generatedSource .forMapper( JavadocAnnotatedWithAttributesMapper.class ) .content(); @@ -44,4 +47,21 @@ public void javadocAnnotatedWithAttributesMapper() { .contains( "@deprecated Use {@link OtherMapper} instead" ) .contains( "@since 0.1" ); } + + @ProcessorTest + @IssueKey("2987") + @WithClasses({ ErroneousJavadocMapper.class }) + @ExpectedCompilationOutcome( + value = CompilationResult.FAILED, + diagnostics = { + @Diagnostic(type = ErroneousJavadocMapper.class, + kind = javax.tools.Diagnostic.Kind.ERROR, + line = 15, + message = "'value', 'authors', 'deprecated' and 'since' are undefined in @Javadoc, " + + "define at least one of them.") + } + ) + void shouldFailOnEmptyJavadocAnnotation() { + } + } From 3e847f692b7e996bd9de3b6e770783784d317a41 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Carlos=20Campanero=20Ortiz?= Date: Sun, 30 Apr 2023 17:30:36 +0200 Subject: [PATCH 15/19] Minor Javadocs improvements --- core/src/main/java/org/mapstruct/Javadoc.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/core/src/main/java/org/mapstruct/Javadoc.java b/core/src/main/java/org/mapstruct/Javadoc.java index 8239174834..e628335d52 100644 --- a/core/src/main/java/org/mapstruct/Javadoc.java +++ b/core/src/main/java/org/mapstruct/Javadoc.java @@ -48,7 +48,7 @@ * * *

- * The whole Javadoc comment block can be passed directly: + * The entire Javadoc comment block can be passed directly: *

* 

  * @Javadoc("This is the description\n"

From a8664ed69555550e3771dfe40e780e413aee9e79 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jos=C3=A9=20Carlos=20Campanero=20Ortiz?=
 
Date: Sun, 30 Apr 2023 17:31:01 +0200
Subject: [PATCH 16/19] Add Javadoc annotation documentation.

---
 .../chapter-3-defining-a-mapper.asciidoc      | 100 ++++++++++++++++++
 1 file changed, 100 insertions(+)

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 e4a77f5391..72c4240027 100644
--- 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 {
+    //...
+}
+----
+====
\ No newline at end of file

From 4b832c6510f525be607c11d0a6655bd52c48df4c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jos=C3=A9=20Carlos=20Campanero=20Ortiz?=
 
Date: Sun, 30 Apr 2023 18:06:08 +0200
Subject: [PATCH 17/19] Add fixtures to test Javadoc annotation.

---
 .../ap/test/javadoc/JavadocTest.java          | 17 ++----------
 ...adocAnnotatedWithAttributesMapperImpl.java | 27 +++++++++++++++++++
 .../JavadocAnnotatedWithValueMapperImpl.java  | 27 +++++++++++++++++++
 3 files changed, 56 insertions(+), 15 deletions(-)
 create mode 100644 processor/src/test/resources/fixtures/org/mapstruct/ap/test/javadoc/JavadocAnnotatedWithAttributesMapperImpl.java
 create mode 100644 processor/src/test/resources/fixtures/org/mapstruct/ap/test/javadoc/JavadocAnnotatedWithValueMapperImpl.java

diff --git a/processor/src/test/java/org/mapstruct/ap/test/javadoc/JavadocTest.java b/processor/src/test/java/org/mapstruct/ap/test/javadoc/JavadocTest.java
index a34319eba1..316114389f 100644
--- a/processor/src/test/java/org/mapstruct/ap/test/javadoc/JavadocTest.java
+++ b/processor/src/test/java/org/mapstruct/ap/test/javadoc/JavadocTest.java
@@ -5,7 +5,6 @@
  */
 package org.mapstruct.ap.test.javadoc;
 
-import org.assertj.core.api.AbstractCharSequenceAssert;
 import org.junit.jupiter.api.extension.RegisterExtension;
 import org.mapstruct.ap.testutil.IssueKey;
 import org.mapstruct.ap.testutil.ProcessorTest;
@@ -27,25 +26,13 @@ class JavadocTest {
     @ProcessorTest
     @WithClasses( { JavadocAnnotatedWithValueMapper.class } )
     void javadocAnnotatedWithValueMapper() {
-        AbstractCharSequenceAssert content = generatedSource
-                .forMapper( JavadocAnnotatedWithValueMapper.class )
-                .content();
-        content
-                       .contains( "This is the description" );
+        generatedSource.addComparisonToFixtureFor( JavadocAnnotatedWithValueMapper.class );
     }
 
     @ProcessorTest
     @WithClasses( { JavadocAnnotatedWithAttributesMapper.class } )
     void javadocAnnotatedWithAttributesMapper() {
-        AbstractCharSequenceAssert content = generatedSource
-                .forMapper( JavadocAnnotatedWithAttributesMapper.class )
-                .content();
-        content
-                .contains( "This is the description" )
-                .contains( "@author author1" )
-                .contains( "@author author2" )
-                .contains( "@deprecated Use {@link OtherMapper} instead" )
-                .contains( "@since 0.1" );
+        generatedSource.addComparisonToFixtureFor( JavadocAnnotatedWithAttributesMapper.class );
     }
 
     @ProcessorTest
diff --git a/processor/src/test/resources/fixtures/org/mapstruct/ap/test/javadoc/JavadocAnnotatedWithAttributesMapperImpl.java b/processor/src/test/resources/fixtures/org/mapstruct/ap/test/javadoc/JavadocAnnotatedWithAttributesMapperImpl.java
new file mode 100644
index 0000000000..53b9a08e92
--- /dev/null
+++ b/processor/src/test/resources/fixtures/org/mapstruct/ap/test/javadoc/JavadocAnnotatedWithAttributesMapperImpl.java
@@ -0,0 +1,27 @@
+/*
+ * 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.test.javadoc;
+
+import javax.annotation.processing.Generated;
+
+/**
+* This is the description
+*
+* @author author1
+* @author author2
+*
+* @deprecated Use {@link OtherMapper} instead
+*
+* @since 0.1
+*/
+@Generated(
+    value = "org.mapstruct.ap.MappingProcessor",
+    date = "2023-04-30T17:36:38+0200",
+    comments = "version: , compiler: javac, environment: Java 11.0.18 (Ubuntu)"
+)
+@Deprecated
+public class JavadocAnnotatedWithAttributesMapperImpl implements JavadocAnnotatedWithAttributesMapper {
+}
diff --git a/processor/src/test/resources/fixtures/org/mapstruct/ap/test/javadoc/JavadocAnnotatedWithValueMapperImpl.java b/processor/src/test/resources/fixtures/org/mapstruct/ap/test/javadoc/JavadocAnnotatedWithValueMapperImpl.java
new file mode 100644
index 0000000000..7bcc54ca44
--- /dev/null
+++ b/processor/src/test/resources/fixtures/org/mapstruct/ap/test/javadoc/JavadocAnnotatedWithValueMapperImpl.java
@@ -0,0 +1,27 @@
+/*
+ * 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.test.javadoc;
+
+import javax.annotation.processing.Generated;
+
+/**
+* This is the description
+*
+* @author author1
+* @author author2
+*
+* @deprecated Use {@link OtherMapper} instead
+* @since 0.1
+*
+*/
+@Generated(
+    value = "org.mapstruct.ap.MappingProcessor",
+    date = "2023-04-30T17:38:45+0200",
+    comments = "version: , compiler: javac, environment: Java 11.0.18 (Ubuntu)"
+)
+@Deprecated
+public class JavadocAnnotatedWithValueMapperImpl implements JavadocAnnotatedWithValueMapper {
+}

From 1c13dffc260db8e597220ed08e7fe31136019e97 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jos=C3=A9=20Carlos=20Campanero=20Ortiz?=
 
Date: Sun, 30 Apr 2023 18:12:37 +0200
Subject: [PATCH 18/19] Update
 documentation/src/main/asciidoc/chapter-3-defining-a-mapper.asciidoc

Co-authored-by: Filip Hrisafov 
---
 .../src/main/asciidoc/chapter-3-defining-a-mapper.asciidoc      | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

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 72c4240027..05871bec99 100644
--- a/documentation/src/main/asciidoc/chapter-3-defining-a-mapper.asciidoc
+++ b/documentation/src/main/asciidoc/chapter-3-defining-a-mapper.asciidoc
@@ -767,7 +767,7 @@ public class MyConverterImpl implements MyConverter {
 === Adding Javadoc comments
 
 MapStruct provides support for defining Javadoc comments in the generated mapper implementation using the
-`org.mapstruct.Javadoc annotation.
+`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.

From e0aa5702730b2d69d7756e80a297c36611851310 Mon Sep 17 00:00:00 2001
From: Filip Hrisafov 
Date: Mon, 1 May 2023 09:10:03 +0200
Subject: [PATCH 19/19] Small javadoc polishing

---
 core/src/main/java/org/mapstruct/Javadoc.java | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)

diff --git a/core/src/main/java/org/mapstruct/Javadoc.java b/core/src/main/java/org/mapstruct/Javadoc.java
index e628335d52..4b5d2fb839 100644
--- a/core/src/main/java/org/mapstruct/Javadoc.java
+++ b/core/src/main/java/org/mapstruct/Javadoc.java
@@ -13,7 +13,6 @@
 /**
  * Allows the definition of Javadoc comments in the MapStruct Mapper generated class.
  *
- *
  * 
The annotation provides support for the usual Javadoc comments elements by defining analogous attributes.

  *
  *
@@ -88,17 +87,17 @@
 
     /**
      * List of authors of the code that it is being documented.
-     *
-     * It will generated a list of the Javadoc tool comment element @author
+     * 

+     * It will generate a list of the Javadoc tool comment element @author
      * with the different values and in the order provided.
      *
-     * @return List of authors of the functionality being documented.
+     * @return array of javadoc authors.
      */
     String[] authors() default { };
 
     /**
      * Specifies that the functionality that is being documented is deprecated.
-     *
+     * 

      * Corresponds to the @deprecated Javadoc tool comment element.
      *
      * @return Deprecation message about the documented functionality
@@ -107,7 +106,7 @@
 
     /**
      * Specifies the version since the functionality that is being documented is available.
-     *
+     * 

      * Corresponds to the @since Javadoc tool comment element.
      *
      * @return Version since the functionality is available