GH-1430 - Include module base package comments in module description of canvases.

The APT now also extracts Javadoc from package-info.java and adds it to the documentation source file the Documenter inspects when creating application module canvases. If such documentation is available, an additional row titled "Description" is added to the canvas.

Author: odrotbohm

spring-modulith-apt/src/main/java/org/springframework/modulith/apt/SpringModulithProcessor.java

@@ -18,6 +18,7 @@
 import io.toolisticon.aptk.tools.ElementUtils;
 import io.toolisticon.aptk.tools.wrapper.ElementWrapper;
 import io.toolisticon.aptk.tools.wrapper.ExecutableElementWrapper;
+import io.toolisticon.aptk.tools.wrapper.PackageElementWrapper;
 import io.toolisticon.aptk.tools.wrapper.TypeElementWrapper;
 
 import java.io.File;
@@ -158,9 +159,7 @@ public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment
 
 			roundEnv.getRootElements().stream()
 					.map(ElementWrapper::wrap)
-					.filter(ElementWrapper::isTypeElement)
-					.map(TypeElementWrapper::toTypeElement)
-					.flatMap(this::handle)
+					.flatMap(this::toMetadata)
 					.forEach(metadata::add);
 
 			return false;
@@ -213,8 +212,20 @@ public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment
 		return false;
 	}
 
-	private Stream<TypeMetadata> handle(TypeElementWrapper type) {
-		return getTypes(type).flatMap(this::toMetadata);
+	private Stream<TypeMetadata> toMetadata(ElementWrapper<?> wrapper) {
+
+		if (wrapper.isTypeElement()) {
+			return getTypes(TypeElementWrapper.toTypeElement(wrapper)).flatMap(this::toMetadata);
+		}
+
+		if (wrapper.isPackageElement()) {
+
+			var pkg = PackageElementWrapper.toPackageElement(wrapper);
+
+			return Stream.of(new TypeMetadata(pkg.getPackageName(), getComment(pkg), Collections.emptyList()));
+		}
+
+		return Stream.empty();
 	}
 
 	private Stream<TypeMetadata> toMetadata(TypeElementWrapper it) {

spring-modulith-apt/src/test/java/org/springframework/modulith/apt/SpringModulithProcessorUnitTests.java

@@ -71,6 +71,19 @@ void extractsJavadocFromMethodWithClassNestedInInterfaceAsParameter() {
 		});
 	}
 
+	@Test // GH-1430
+	void extractsPackageComments() throws Exception {
+
+		assertSucceded(getSourceFile("package-info"));
+
+		var output = new File(JSON_LOCATION);
+
+		var context = JsonPath.parse(output);
+		var comment = context.read("$[?(@.name == 'example')].comment", String[].class)[0];
+
+		assertThat(comment).isEqualTo("Test comment.");
+	}
+
 	private static DoCustomAssertions assertSucceded(String source) {
 
 		return assertSourceProcessed(source)

spring-modulith-apt/src/test/resources/example/package-info.java

@@ -0,0 +1,4 @@
+/**
+ * Test comment.
+ */
+package example;

spring-modulith-docs/src/main/java/org/springframework/modulith/docs/Asciidoctor.java

@@ -410,6 +410,10 @@ public String renderBeanReferences(ApplicationModule module) {
 		return bullets.isBlank() ? "None" : bullets;
 	}
 
+	public String renderModuleDescription(ApplicationModule module) {
+		return docSource.get().getDocumentation(module.getBasePackage()).orElse("");
+	}
+
 	public String renderHeadline(int i, String modules) {
 		return "=".repeat(i) + " " + modules + System.lineSeparator();
 	}

spring-modulith-docs/src/main/java/org/springframework/modulith/docs/CodeReplacingDocumentationSource.java

@@ -17,6 +17,7 @@
 
 import java.util.Optional;
 
+import org.springframework.modulith.core.JavaPackage;
 import org.springframework.util.Assert;
 
 import com.tngtech.archunit.core.domain.JavaClass;
@@ -69,4 +70,14 @@ public Optional<String> getDocumentation(JavaClass type) {
 		return delegate.getDocumentation(type)
 				.map(asciidoctor::toAsciidoctor);
 	}
+
+	/*
+	 * (non-Javadoc)
+	 * @see org.springframework.modulith.docs.DocumentationSource#getDocumentation(org.springframework.modulith.core.JavaPackage)
+	 */
+	@Override
+	public Optional<String> getDocumentation(JavaPackage pkg) {
+		return delegate.getDocumentation(pkg)
+				.map(asciidoctor::toAsciidoctor);
+	}
 }

spring-modulith-docs/src/main/java/org/springframework/modulith/docs/DocumentationSource.java

@@ -17,6 +17,8 @@
 
 import java.util.Optional;
 
+import org.springframework.modulith.core.JavaPackage;
+
 import com.tngtech.archunit.core.domain.JavaClass;
 import com.tngtech.archunit.core.domain.JavaMethod;
 
@@ -43,4 +45,13 @@ interface DocumentationSource {
 	 * @since 1.3
 	 */
 	Optional<String> getDocumentation(JavaClass type);
+
+	/**
+	 * Returns the documentation for the given {@link JavaPackage}.
+	 *
+	 * @param pkg must not be {@literal null}.
+	 * @return will never be {@literal null}.
+	 * @since 2.0
+	 */
+	Optional<String> getDocumentation(JavaPackage pkg);
 }

spring-modulith-docs/src/main/java/org/springframework/modulith/docs/Documenter.java

@@ -442,6 +442,7 @@ String toModuleCanvas(ApplicationModule module, CanvasOptions options) {
 
 				.append(startTable("%autowidth.stretch, cols=\"h,a\""))
 				.append(addTableRow("Base package", asciidoctor.toInlineCode(module.getBasePackage().getName()), options))
+				.append(addTableRow("Description", asciidoctor.renderModuleDescription(module), options))
 
 				// Spring components
 				.append(addTableRow("Spring components", asciidoctor.renderSpringBeans(module, options), options)) //

spring-modulith-docs/src/main/java/org/springframework/modulith/docs/SpringModulithDocumentationSource.java

@@ -26,6 +26,7 @@
 import org.jspecify.annotations.Nullable;
 import org.springframework.boot.json.BasicJsonParser;
 import org.springframework.core.io.Resource;
+import org.springframework.modulith.core.JavaPackage;
 import org.springframework.modulith.docs.metadata.MethodMetadata;
 import org.springframework.modulith.docs.metadata.TypeMetadata;
 import org.springframework.modulith.docs.util.BuildSystemUtils;
@@ -114,6 +115,19 @@ public Optional<String> getDocumentation(JavaMethod method) {
 				.filter(StringUtils::hasText);
 	}
 
+	/*
+	 * (non-Javadoc)
+	 * @see org.springframework.modulith.docs.DocumentationSource#getDocumentation(org.springframework.modulith.core.JavaPackage)
+	 */
+	@Override
+	public Optional<String> getDocumentation(JavaPackage pkg) {
+
+		return metadata.stream()
+				.filter(it -> it.name().equals(pkg.getName()))
+				.findFirst()
+				.map(TypeMetadata::comment);
+	}
+
 	@SuppressWarnings("unchecked")
 	private static Collection<TypeMetadata> from(Resource resource) {