absoluteDirs = new ArrayList<>();
+ if (StringUtils.hasText(javadocJsonDirs)) {
+ String[] dirs = javadocJsonDirs.split(PATH_DELIMITER);
+ for (String dir : dirs) {
+ if (StringUtils.hasText(dir)) {
+ absoluteDirs.add(new File(dir.trim()).getAbsoluteFile());
+ }
+ }
+ }
+ return absoluteDirs;
+ }
+
+ /**
+ * Walks up the class hierarchy and interfaces until a comment is found or top most class is reached.
+ *
+ * Javadoc on super classes and Javadoc on interfaces of super classes has precedence over the Javadoc on direct
+ * interfaces of the class. This is only important in the rare case of competing Javadoc comments.
+ *
+ * As we do not know the full method signature here, we can not check whether a method in the super class actually
+ * overwrites the given method. However, the Javadoc model ignores method signatures anyway and it should not cause
+ * issues for the usual use case.
+ */
+ private String resolveCommentFromClassHierarchy(Class javaBaseClass,
+ CommentExtractor commentExtractor) {
+ String comment = commentExtractor.comment(classJavadoc(javaBaseClass));
+ if (StringUtils.hasText(comment)) {
+ // Direct Javadoc on a method always wins.
+ return comment;
+ }
+ // Super class has precedence over interfaces, but this also means that interfaces
+ // of super classes have precedence over interfaces of the class itself.
+ if (javaBaseClass.getSuperclass() != null) {
+ String superClassComment = resolveCommentFromClassHierarchy(javaBaseClass.getSuperclass(),
+ commentExtractor);
+ if (StringUtils.hasText(superClassComment)) {
+ return superClassComment;
+ }
+ }
+ for (Class i : javaBaseClass.getInterfaces()) {
+ String interfaceComment = resolveCommentFromClassHierarchy(i, commentExtractor);
+ if (StringUtils.hasText(interfaceComment)) {
+ return interfaceComment;
+ }
+ }
+ return "";
+ }
+
+ private interface CommentExtractor {
+ String comment(ClassJavadoc classJavadoc);
+ }
+ }
}
diff --git a/spring-modulith-docs/src/main/java/org/springframework/modulith/docs/SpringModulithDocumentationSource.java b/spring-modulith-docs/src/main/java/org/springframework/modulith/docs/SpringModulithDocumentationSource.java
new file mode 100644
index 00000000..dfae4aeb
--- /dev/null
+++ b/spring-modulith-docs/src/main/java/org/springframework/modulith/docs/SpringModulithDocumentationSource.java
@@ -0,0 +1,165 @@
+/*
+ * Copyright 2024 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.modulith.docs;
+
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.util.Collection;
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+
+import org.springframework.boot.json.BasicJsonParser;
+import org.springframework.core.io.Resource;
+import org.springframework.lang.Nullable;
+import org.springframework.modulith.docs.metadata.MethodMetadata;
+import org.springframework.modulith.docs.metadata.TypeMetadata;
+import org.springframework.modulith.docs.util.BuildSystemUtils;
+import org.springframework.util.Assert;
+import org.springframework.util.StringUtils;
+
+import com.tngtech.archunit.core.domain.JavaClass;
+import com.tngtech.archunit.core.domain.JavaMethod;
+
+/**
+ * A {@link DocumentationSource} using metadata found in {@value #METADATA_FILE}, usually generated via
+ * {@code spring-modulith-apt}.
+ *
+ * @author Oliver Drotbohm
+ * @since 1.3
+ * @see the {@code spring-modulith-apt} artifact.
+ */
+class SpringModulithDocumentationSource implements DocumentationSource {
+
+ private static final String METADATA_FILE = "generated-spring-modulith/javadoc.json";
+ private static final Optional INSTANCE = BuildSystemUtils
+ .getTargetResource(METADATA_FILE).map(SpringModulithDocumentationSource::new);
+
+ private Collection metadata;
+
+ /**
+ * Creates a new {@link SpringModulithDocumentationSource} for the given file.
+ *
+ * @param resource must not be {@literal null}.
+ */
+ private SpringModulithDocumentationSource(Resource resource) {
+
+ Assert.notNull(resource, "Resource must not be null!");
+
+ this.metadata = from(resource);
+ }
+
+ /**
+ * Creates a new {@link DocumentationSource} if the backing metadata file (in {@value #METADATA_FILE}) is present.
+ *
+ * @return will never be {@literal null}.
+ */
+ public static Optional getInstance() {
+ return INSTANCE;
+ }
+
+ /**
+ * Returns the location of the metadata file.
+ *
+ * @return will never be {@literal null}.
+ */
+ public static String getMetadataLocation() {
+ return METADATA_FILE;
+ }
+
+ /*
+ * (non-Javadoc)
+ * @see org.springframework.modulith.docs.DocumentationSource#getDocumentation(com.tngtech.archunit.core.domain.JavaClass)
+ */
+ @Override
+ public Optional getDocumentation(JavaClass type) {
+
+ return metadata.stream()
+ .filter(it -> it.name().equals(type.getName()))
+ .findFirst()
+ .map(TypeMetadata::comment)
+ .filter(StringUtils::hasText);
+ }
+
+ /*
+ * (non-Javadoc)
+ * @see org.springframework.modulith.docs.DocumentationSource#getDocumentation(com.tngtech.archunit.core.domain.JavaMethod)
+ */
+ @Override
+ public Optional getDocumentation(JavaMethod method) {
+
+ var owner = method.getOwner();
+
+ return metadata.stream()
+ .filter(it -> it.name().equals(owner.getName()))
+ .findFirst()
+ .stream()
+ .flatMap(it -> it.methods().stream())
+ .filter(it -> it.hasSignatureOf(method.reflect()))
+ .findFirst()
+ .map(MethodMetadata::comment)
+ .filter(StringUtils::hasText);
+ }
+
+ @SuppressWarnings("unchecked")
+ private static Collection from(Resource resource) {
+
+ try {
+
+ var content = resource.getContentAsString(StandardCharsets.UTF_8);
+ var parsed = new BasicJsonParser().parseList(content);
+
+ return parsed.stream()
+ .map(it -> it instanceof TypeMetadata metadata ? metadata : typeMetadata((Map) it))
+ .toList();
+
+ } catch (IOException o_O) {
+ throw new RuntimeException(o_O);
+ }
+ }
+
+ @SuppressWarnings("unchecked")
+ private static TypeMetadata typeMetadata(Map source) {
+
+ var methods = source.containsKey("methods")
+ ? ((List>) source.get("methods")).stream()
+ .map(SpringModulithDocumentationSource::methodMetadata)
+ .toList()
+ : Collections. emptyList();
+
+ return new TypeMetadata(
+ source.get("name").toString(),
+ getString(source, "comment"),
+ methods);
+ }
+
+ private static MethodMetadata methodMetadata(Map source) {
+
+ return new MethodMetadata(
+ source.get("name").toString(),
+ source.get("signature").toString(),
+ getString(source, "comment"));
+ }
+
+ @Nullable
+ private static String getString(Map source, String key) {
+
+ Object result = source.get(key);
+
+ return result == null ? null : result.toString();
+ }
+}
diff --git a/spring-modulith-docs/src/main/java/org/springframework/modulith/docs/metadata/MethodMetadata.java b/spring-modulith-docs/src/main/java/org/springframework/modulith/docs/metadata/MethodMetadata.java
new file mode 100644
index 00000000..6b2629f1
--- /dev/null
+++ b/spring-modulith-docs/src/main/java/org/springframework/modulith/docs/metadata/MethodMetadata.java
@@ -0,0 +1,49 @@
+/*
+ * Copyright 2024 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.modulith.docs.metadata;
+
+import java.lang.reflect.Method;
+import java.util.Arrays;
+import java.util.stream.Collectors;
+
+import org.springframework.lang.Nullable;
+import org.springframework.util.Assert;
+
+/**
+ * Metadata about a Java {@link Method}.
+ *
+ * @author Oliver Drotbohm
+ * @since 1.3
+ */
+public record MethodMetadata(String name, String signature, @Nullable String comment) {
+
+ /**
+ * Returns whether the method represented has the same signature as the given one.
+ *
+ * @param method must not be {@literal null}.
+ * @return
+ */
+ public boolean hasSignatureOf(Method method) {
+
+ Assert.notNull(method, "Method must not be null!");
+
+ var parameters = Arrays.stream(method.getParameterTypes())
+ .map(Class::getName)
+ .collect(Collectors.joining(", ", "(", ")"));
+
+ return signature.equals(method.getName().concat(parameters));
+ }
+}
diff --git a/spring-modulith-docs/src/main/java/org/springframework/modulith/docs/metadata/TypeMetadata.java b/spring-modulith-docs/src/main/java/org/springframework/modulith/docs/metadata/TypeMetadata.java
new file mode 100644
index 00000000..6902fc61
--- /dev/null
+++ b/spring-modulith-docs/src/main/java/org/springframework/modulith/docs/metadata/TypeMetadata.java
@@ -0,0 +1,28 @@
+/*
+ * Copyright 2024 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.modulith.docs.metadata;
+
+import java.util.List;
+
+import org.springframework.lang.Nullable;
+
+/**
+ * Metadata about a Java type.
+ *
+ * @author Oliver Drotbohm
+ * @since 1.3
+ */
+public record TypeMetadata(String name, @Nullable String comment, List methods) {}
diff --git a/spring-modulith-docs/src/main/java/org/springframework/modulith/docs/util/BuildSystemUtils.java b/spring-modulith-docs/src/main/java/org/springframework/modulith/docs/util/BuildSystemUtils.java
new file mode 100644
index 00000000..62a3a2a2
--- /dev/null
+++ b/spring-modulith-docs/src/main/java/org/springframework/modulith/docs/util/BuildSystemUtils.java
@@ -0,0 +1,72 @@
+/*
+ * Copyright 2024 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.modulith.docs.util;
+
+import java.io.File;
+import java.util.Optional;
+
+import org.springframework.core.io.FileSystemResource;
+import org.springframework.core.io.Resource;
+import org.springframework.util.Assert;
+
+/**
+ * Utilities to detect the build system used.
+ *
+ * @author Oliver Drotbohm
+ * @since 1.3
+ */
+public class BuildSystemUtils {
+
+ /**
+ * Returns a path to a resource in the build target folder.
+ *
+ * @param path must not be {@literal null} or empty.
+ * @return will never be {@literal null}.
+ */
+ public static String getTarget(String path) {
+
+ Assert.notNull(path, "Path must not be null!");
+
+ return getTargetFolder() + (path.startsWith("/") ? path : "/" + path);
+ }
+
+ /**
+ * Returns a {@link Resource} in the build target folder.
+ *
+ * @param path must not be {@literal null} or empty.
+ * @return will never be {@literal null}.
+ */
+ public static Optional getTargetResource(String path) {
+ return Optional. of(new FileSystemResource(getTarget(path))).filter(Resource::exists);
+ }
+
+ /**
+ * Returns the path to the folder containing test classes.
+ *
+ * @return will never be {@literal null}.
+ */
+ public static String getTestTarget() {
+ return isMaven() ? "target/test-classes" : "build/classes/java/test";
+ }
+
+ private static String getTargetFolder() {
+ return isMaven() ? "target" : "build";
+ }
+
+ private static boolean isMaven() {
+ return new File("pom.xml").exists();
+ }
+}
diff --git a/spring-modulith-starters/spring-modulith-starter-core/pom.xml b/spring-modulith-starters/spring-modulith-starter-core/pom.xml
index 501c73bf..e035fad7 100644
--- a/spring-modulith-starters/spring-modulith-starter-core/pom.xml
+++ b/spring-modulith-starters/spring-modulith-starter-core/pom.xml
@@ -24,6 +24,12 @@
1.3.0-SNAPSHOT
+
+ org.springframework.modulith
+ spring-modulith-apt
+ 1.3.0-SNAPSHOT
+
+
org.springframework.modulith
spring-modulith-core
diff --git a/src/docs/antora/modules/ROOT/pages/appendix.adoc b/src/docs/antora/modules/ROOT/pages/appendix.adoc
index f3ef222e..44221311 100644
--- a/src/docs/antora/modules/ROOT/pages/appendix.adoc
+++ b/src/docs/antora/modules/ROOT/pages/appendix.adoc
@@ -101,6 +101,7 @@ Usually propagated in CI environments to consider all changes since the last suc
|`spring-modulith-starter-core`
|`compile`
a|* `spring-modulith-api`
+* `spring-modulith-apt`
* `spring-modulith-moments`
* `spring-modulith-core` (runtime)
* `spring-modulith-runtime` (runtime)
@@ -155,6 +156,7 @@ a|* `spring-modulith-docs`
|Module|Typical scope|Description
|`spring-modulith-actuator`|`runtime`|A Spring Boot actuator to expose the application module structure via an actuator.
|`spring-modulith-api`|`compile`|The abstractions to be used in your production code to customize Spring Modulith's default behavior.
+|`spring-modulith-apt`|`compile`|An annotation processor to extract Javadoc for inclusion in xref:documentation.adoc#application-module-canvas[Application Module Canvases].
|`spring-modulith-core`|`runtime`|The core application module model and API.
|`spring-modulith-docs`|`test`|The `Documenter` API to create Asciidoctor and PlantUML documentation from the module model.
|`spring-modulith-events-amqp`|`runtime`|Event externalization support for AMQP.