Spring/spring-modulith
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

GH-111 - Package and publish Javadoc.

Browse Source 
A lot of Javadoc polish. Not done yet.
This commit is contained in:
Oliver Drotbohm
2023-01-12 01:21:44 +01:00
parent 9a01404ce2
commit 0d009f06c9
33 changed files with 218 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

43
pom.xml
View File

@@ -42,6 +42,7 @@
<jmolecules-bom.version>2022.2.2</jmolecules-bom.version>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
<spring.version>6.0.4</spring.version> <!-- For Javadoc links only -->
<spring-asciidoctor-backends.version>0.0.4</spring-asciidoctor-backends.version>
<spring-boot.version>3.0.1</spring-boot.version>
@@ -132,11 +133,6 @@ limitations under the License.
</goals>
</execution>
</executions>
<configuration>
<doclint>none</doclint>
<quiet>true</quiet>
<show>package</show>
</configuration>
</plugin>
</plugins>
@@ -225,7 +221,6 @@ limitations under the License.
<properties>
<generated-docs.directory>${project.build.directory}/generated-docs</generated-docs.directory>
<maven.main.skip>true</maven.main.skip>
<maven.test.skip>true</maven.test.skip>
<maven.install.skip>true</maven.install.skip>
<maven.deploy.skip>true</maven.deploy.skip>
@@ -240,6 +235,22 @@ limitations under the License.
<artifactId>artifactory-maven-plugin</artifactId>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>3.4.1</version>
<inherited>false</inherited>
<executions>
<execution>
<id>aggregate-javadocs</id>
<goals>
<goal>aggregate-no-fork</goal>
</goals>
<phase>package</phase>
</execution>
</executions>
</plugin>
</plugins>
<pluginManagement>
@@ -423,6 +434,26 @@ limitations under the License.
<defaultGoal>verify</defaultGoal>
<pluginManagement>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>3.4.1</version>
<configuration>
<doclint>accessibility,html,reference,syntax</doclint>
<show>package</show>
<quiet>true</quiet>
<links>
<link>https://docs.spring.io/spring-boot/docs/${spring-boot.version}/api/</link>
<link>https://docs.spring.io/spring/docs/${spring.version}/javadoc-api/</link>
<link>https://docs.oracle.com/en/java/javase/17/docs/api/</link>
</links>
</configuration>
</plugin>
</plugins>
</pluginManagement>
<plugins>
<plugin>

2
spring-modulith-actuator/src/main/java/org/springframework/modulith/actuator/ApplicationModulesEndpoint.java
View File

@@ -62,7 +62,7 @@ public class ApplicationModulesEndpoint {
private final Supplier<ApplicationModules> runtime;
/**
* Creates a new {@link ApplicationModulesEndpoint} for the given {@link ModulesRuntime}.
* Creates a new {@link ApplicationModulesEndpoint} for the given {@link ApplicationModules}.
*
* @param runtime must not be {@literal null}.
*/

5
spring-modulith-actuator/src/main/java/org/springframework/modulith/actuator/autoconfigure/package-info.java Normal file
View File

@@ -0,0 +1,5 @@
/**
* Autoconfiguration for Spring Modulith actuators.
*/
@org.springframework.lang.NonNullApi
package org.springframework.modulith.actuator.autoconfigure;

5
spring-modulith-actuator/src/main/java/org/springframework/modulith/actuator/package-info.java Normal file
View File

@@ -0,0 +1,5 @@
/**
* Spring Boot actuator support for Spring Modulith.
*/
@org.springframework.lang.NonNullApi
package org.springframework.modulith.actuator;

5
spring-modulith-api/src/main/java/org/springframework/modulith/package-info.java Normal file
View File

@@ -0,0 +1,5 @@
/**
* Core abstractions of Spring Modulith. To be referred to in user applications.
*/
@org.springframework.lang.NonNullApi
package org.springframework.modulith;

56
spring-modulith-core/src/main/java/org/springframework/modulith/model/ApplicationModuleInformation.java
View File

@@ -22,7 +22,9 @@ import java.util.Optional;
import java.util.function.Supplier;
import java.util.stream.Stream;
import org.jmolecules.ddd.annotation.Module;
import org.springframework.modulith.ApplicationModule;
import org.springframework.util.Assert;
import org.springframework.util.ClassUtils;
import org.springframework.util.StringUtils;
@@ -34,24 +36,46 @@ import org.springframework.util.StringUtils;
*/
interface ApplicationModuleInformation {
/**
* Creates a new {@link ApplicationModuleInformation} for the given {@link JavaPackage}.
*
* @param javaPackage must not be {@literal null}.
* @return will never be {@literal null}.
*/
public static ApplicationModuleInformation of(JavaPackage javaPackage) {
if (ClassUtils.isPresent("org.jmolecules.ddd.annotation.Module",
ApplicationModuleInformation.class.getClassLoader())
&& MoleculesModule.supports(javaPackage)) {
return new MoleculesModule(javaPackage);
&& JMoleculesModule.supports(javaPackage)) {
return new JMoleculesModule(javaPackage);
}
return new ModulithsModule(javaPackage);
return new SpringModulithModule(javaPackage);
}
/**
* Returns the display name to be used to describe the module.
*
* @return will never be {@literal null}.
*/
default Optional<String> getDisplayName() {
return Optional.empty();
}
/**
* Returns all allowed dependencies.
*
* @return will never be {@literal null}.
*/
List<String> getAllowedDependencies();
static class MoleculesModule implements ApplicationModuleInformation {
/**
* An {@link ApplicationModuleInformation} for the jMolecules {@link Module} annotation.
*
* @author Oliver Drotbohm
* @see <a href="https://jmolecules.org">https://jMolecules.org</a>
*/
static class JMoleculesModule implements ApplicationModuleInformation {
private final Optional<org.jmolecules.ddd.annotation.Module> annotation;
@@ -59,7 +83,7 @@ interface ApplicationModuleInformation {
return javaPackage.getAnnotation(org.jmolecules.ddd.annotation.Module.class).isPresent();
}
public MoleculesModule(JavaPackage javaPackage) {
public JMoleculesModule(JavaPackage javaPackage) {
this.annotation = javaPackage.getAnnotation(org.jmolecules.ddd.annotation.Module.class);
}
@@ -90,15 +114,33 @@ interface ApplicationModuleInformation {
}
}
static class ModulithsModule implements ApplicationModuleInformation {
/**
* An {@link ApplicationModuleInformation} that inspects the {@link ApplicationModule} annotation.
*
* @author Oliver Drotbohm
*/
static class SpringModulithModule implements ApplicationModuleInformation {
private final Optional<ApplicationModule> annotation;
/**
* Whether the given {@link JavaPackage} supports this {@link ApplicationModuleInformation}.
*
* @param javaPackage must not be {@literal null}.
*/
public static boolean supports(JavaPackage javaPackage) {
Assert.notNull(javaPackage, "Java package must not be null!");
return javaPackage.getAnnotation(ApplicationModule.class).isPresent();
}
public ModulithsModule(JavaPackage javaPackage) {
/**
* Creates a new {@link SpringModulithModule} for the given {@link JavaPackage}.
*
* @param javaPackage must not be {@literal null}.
*/
public SpringModulithModule(JavaPackage javaPackage) {
this.annotation = javaPackage.getAnnotation(ApplicationModule.class);
}

5
spring-modulith-core/src/main/java/org/springframework/modulith/model/ApplicationModules.java
View File

@@ -154,7 +154,7 @@ public class ApplicationModules implements Iterable<ApplicationModule> {
* annotation on the class given for advanced customizations of the module setup.
*
* @param modulithType must not be {@literal null}.
* @return
* @return will never be {@literal null}.
*/
public static ApplicationModules of(Class<?> modulithType) {
return of(modulithType, alwaysFalse());
@@ -167,9 +167,8 @@ public class ApplicationModules implements Iterable<ApplicationModule> {
* of the module setup.
*
* @param modulithType must not be {@literal null}.
* @param detection must not be {@literal null}.
* @param ignored must not be {@literal null}.
* @return
* @return will never be {@literal null}.
*/
public static ApplicationModules of(Class<?> modulithType, DescribedPredicate<JavaClass> ignored) {

2
spring-modulith-core/src/main/java/org/springframework/modulith/model/JavaPackage.java
View File

@@ -37,6 +37,8 @@ import com.tngtech.archunit.thirdparty.com.google.common.base.Supplier;
import com.tngtech.archunit.thirdparty.com.google.common.base.Suppliers;
/**
* An abstraction of a Java package.
*
* @author Oliver Drotbohm
*/
public class JavaPackage implements DescribedIterable<JavaClass> {

4
spring-modulith-core/src/main/java/org/springframework/modulith/model/ModulithMetadata.java
View File

@@ -30,8 +30,8 @@ public interface ModulithMetadata {
static final String ANNOTATION_MISSING = "Modules can only be retrieved from a root type, but %s is not annotated with either @%s, @%s or @%s!";
/**
* Creates a new {@link ModulithMetadata} for the given annotated type. Expecteds the type either be annotated with
* {@link Modulith}, {@link Modulithic} or {@link SpringBootApplication}.
* Creates a new {@link ModulithMetadata} for the given annotated type. Expects the type either be annotated with
* {@link Modulith}, {@link Modulithic} or {@link org.springframework.boot.autoconfigure.SpringBootApplication}.
*
* @param annotated must not be {@literal null}.
* @return

3
spring-modulith-core/src/main/java/org/springframework/modulith/model/package-info.java
View File

@@ -1,2 +1,5 @@
/**
* Core, internal abstractions of Spring Modulith.
*/
@org.springframework.lang.NonNullApi
package org.springframework.modulith.model;

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

@@ -74,6 +74,7 @@ public class Documenter {
private static final Map<DependencyType, String> DEPENDENCY_DESCRIPTIONS = new LinkedHashMap<>();
private static final String INVALID_FILE_NAME_PATTERN = "Configured file name pattern does not include a '%s' placeholder for the module name!";
private static final String DEFAULT_LOCATION = "spring-modulith-docs";
static {
DEPENDENCY_DESCRIPTIONS.put(DependencyType.EVENT_LISTENER, "listens to");
@@ -576,7 +577,7 @@ public class Documenter {
* @return will never be {@literal null}.
*/
private static String getDefaultOutputDirectory() {
return (new File("pom.xml").exists() ? "target" : "build").concat("/spring-modulith-docs");
return (new File("pom.xml").exists() ? "target" : "build").concat("/").concat(DEFAULT_LOCATION);
}
private static record Connection(Element source, Element target) {
@@ -658,7 +659,7 @@ public class Documenter {
/**
* A {@link Predicate} to define the which modules to exclude from the diagram to be created.
*/
public DiagramOptions withExcusions(Predicate<ApplicationModule> exclusions) {
public DiagramOptions withExclusions(Predicate<ApplicationModule> exclusions) {
return new DiagramOptions(dependencyTypes, dependencyDepth, exclusions, componentFilter, targetOnly,
targetFileName, colorSelector, defaultDisplayName, style, elementsWithoutRelationships);
}
@@ -708,7 +709,7 @@ public class Documenter {
}
/**
* Which style to render the diagram in. Defaults to {@value DiagramStyle#UML}.
* Which style to render the diagram in. Defaults to {@link DiagramStyle#UML}.
*/
public DiagramOptions withStyle(DiagramStyle style) {
return new DiagramOptions(dependencyTypes, dependencyDepth, exclusions, componentFilter, targetOnly,
@@ -717,7 +718,7 @@ public class Documenter {
/**
* Configuration setting to define whether modules that do not have a relationship to any other module shall be
* retained in the diagrams created. The default is {@value ElementsWithoutRelationships#HIDDEN}. See
* retained in the diagrams created. The default is {@link ElementsWithoutRelationships#HIDDEN}. See
* {@link DiagramOptions#withExclusions(Predicate)} for a more fine-grained way of defining which modules to exclude
* in case you flip this to {@link ElementsWithoutRelationships#VISIBLE}.
*
@@ -785,14 +786,14 @@ public class Documenter {
/**
* A C4 model component diagram.
*
* @see https://c4model.com/#ComponentDiagram
* @see <a href="https://c4model.com/#ComponentDiagram">https://c4model.com/#ComponentDiagram</a>
*/
C4;
}
/**
* Configuration setting to define whether modules that do not have a relationship to any other module shall be
* retained in the diagrams created. The default is {@value ElementsWithoutRelationships#HIDDEN}. See
* retained in the diagrams created. The default is {@link ElementsWithoutRelationships#HIDDEN}. See
* {@link DiagramOptions#withExclusions(Predicate)} for a more fine-grained way of defining which modules to exclude
* in case you flip this to {@link ElementsWithoutRelationships#VISIBLE}.
*

3
spring-modulith-docs/src/main/java/org/springframework/modulith/docs/package-info.java
View File

@@ -1,2 +1,5 @@
/**
* Documentation support for Spring Modulith.
*/
@org.springframework.lang.NonNullApi
package org.springframework.modulith.docs;

3
spring-modulith-events/spring-modulith-events-core/src/main/java/org/springframework/modulith/events/config/package-info.java
View File

@@ -1,2 +1,5 @@
/**
* Spring configuration for the event publication registry.
*/
@org.springframework.lang.NonNullApi
package org.springframework.modulith.events.config;

3
spring-modulith-events/spring-modulith-events-core/src/main/java/org/springframework/modulith/events/package-info.java
View File

@@ -1,2 +1,5 @@
/**
* The event publication registry abstraction.
*/
@org.springframework.lang.NonNullApi
package org.springframework.modulith.events;

7
spring-modulith-events/spring-modulith-events-core/src/main/java/org/springframework/modulith/events/support/CompletionRegisteringBeanPostProcessor.java
View File

@@ -42,10 +42,9 @@ import org.springframework.util.ReflectionUtils;
import org.springframework.util.ReflectionUtils.MethodCallback;
/**
* {@link BeanPostProcessor} that will add a
* {@link CompletionRegisteringBeanPostProcessor.ProxyCreatingMethodCallback.CompletionRegisteringMethodInterceptor} to
* the bean in case it carries a {@link TransactionalEventListener} annotation so that the successful invocation of
* those methods mark the event publication to those listeners as completed.
* {@link BeanPostProcessor} that will add a {@link CompletionRegisteringMethodInterceptor} to the bean in case it
* carries a {@link TransactionalEventListener} annotation so that the successful invocation of those methods mark the
* event publication to those listeners as completed.
*
* @author Oliver Drotbohm
*/

6
spring-modulith-events/spring-modulith-events-core/src/main/java/org/springframework/modulith/events/support/PersistentApplicationEventMulticaster.java
View File

@@ -151,11 +151,11 @@ public class PersistentApplicationEventMulticaster extends AbstractApplicationEv
/**
* First-class collection to work with transactional event listeners, i.e. {@link ApplicationListener} instances that
* implement {@link TransactionalEventListenerMetadata}.
* implement {@link TransactionalApplicationListener}.
*
* @author Oliver Drotbohm
* @see TransactionalEventListener
* @see TransactionalEventListenerMetadata
* @see TransactionalApplicationListener
*/
static class TransactionalEventListeners {
@@ -163,7 +163,7 @@ public class PersistentApplicationEventMulticaster extends AbstractApplicationEv
/**
* Creates a new {@link TransactionalEventListeners} instance by filtering all elements implementing
* {@link TransactionalEventListenerMetadata}.
* {@link TransactionalApplicationListener}.
*
* @param listeners must not be {@literal null}.
*/

3
spring-modulith-events/spring-modulith-events-core/src/main/java/org/springframework/modulith/events/support/package-info.java
View File

@@ -1,2 +1,5 @@
/**
* Spring Framework extensions to integrate the event publication registry.
*/
@org.springframework.lang.NonNullApi
package org.springframework.modulith.events.support;

3
spring-modulith-events/spring-modulith-events-jackson/src/main/java/org/springframework/modulith/events/jackson/package-info.java
View File

@@ -1,2 +1,5 @@
/**
* A Jackson based implementation of the {@link org.springframework.modulith.events.EventSerializer}.
*/
@org.springframework.lang.NonNullApi
package org.springframework.modulith.events.jackson;

3
spring-modulith-events/spring-modulith-events-jdbc/src/main/java/org/springframework/modulith/events/jdbc/package-info.java
View File

@@ -1,2 +1,5 @@
/**
* JDBC integration for {@link org.springframework.modulith.events.EventPublicationRepository}.
*/
@org.springframework.lang.NonNullApi
package org.springframework.modulith.events.jdbc;

3
spring-modulith-events/spring-modulith-events-jpa/src/main/java/org/springframework/modulith/events/jpa/package-info.java
View File

@@ -1,2 +1,5 @@
/**
* JPA integration for {@link org.springframework.modulith.events.EventPublicationRepository}.
*/
@org.springframework.lang.NonNullApi
package org.springframework.modulith.events.jpa;

3
spring-modulith-events/spring-modulith-events-mongodb/src/main/java/org/springframework/modulith/events/mongodb/package-info.java
View File

@@ -1,2 +1,5 @@
/**
* MongoDB integration for {@link org.springframework.modulith.events.EventPublicationRepository}.
*/
@org.springframework.lang.NonNullApi
package org.springframework.modulith.events.mongodb;

4
spring-modulith-moments/src/main/java/org/springframework/modulith/moments/DayHasPassed.java
View File

@@ -36,7 +36,7 @@ public class DayHasPassed implements DomainEvent {
/**
* Creates a new {@link DayHasPassed} for the given {@link LocalDate}.
*
* @param month must not be {@literal null}.
* @param date must not be {@literal null}.
*/
private DayHasPassed(LocalDate date) {
@@ -48,7 +48,7 @@ public class DayHasPassed implements DomainEvent {
/**
* Creates a new {@link DayHasPassed} for the given {@link LocalDate}.
*
* @param month must not be {@literal null}.
* @param date must not be {@literal null}.
*/
public static DayHasPassed of(LocalDate date) {
return new DayHasPassed(date);

5
spring-modulith-moments/src/main/java/org/springframework/modulith/moments/autoconfigure/package-info.java Normal file
View File

@@ -0,0 +1,5 @@
/**
* Autoconfiguration for the {@link org.springframework.modulith.moments.support.Moments} API.
*/
@org.springframework.lang.NonNullApi
package org.springframework.modulith.moments.autoconfigure;

3
spring-modulith-moments/src/main/java/org/springframework/modulith/moments/package-info.java
View File

@@ -1,2 +1,5 @@
/**
* An Passage-of-Time events implementation.
*/
@org.springframework.lang.NonNullApi
package org.springframework.modulith.moments;

2
spring-modulith-moments/src/main/java/org/springframework/modulith/moments/support/Moments.java
View File

@@ -39,6 +39,8 @@ import org.springframework.scheduling.annotation.Scheduled;
import org.springframework.util.Assert;
/**
* Core component to publish passage-of-time events.
*
* @author Oliver Drotbohm
*/
public class Moments {

20
spring-modulith-moments/src/main/java/org/springframework/modulith/moments/support/MomentsProperties.java
View File

@@ -98,7 +98,7 @@ public class MomentsProperties {
/**
* The {@link ZoneId} to determine times which are attached to the events published. Defaults to
* {@value ZoneOffset#UTC}.
* {@link ZoneOffset#UTC}.
*
* @return will never be {@literal null}.
*/
@@ -107,7 +107,7 @@ public class MomentsProperties {
}
/**
* The {@link Locale} to use when determining week boundaries. Defaults to {@value Locale#getDefault()}.
* The {@link Locale} to use when determining week boundaries. Defaults to {@link Locale#getDefault()}.
*
* @return will never be {@literal null}.
*/
@@ -154,8 +154,22 @@ public class MomentsProperties {
return new MomentsProperties(granularity, zoneId, locale, enableTimeMachine, quarters);
}
/**
* The granularity of events to publish.
*
* @author Oliver Drotbohm
*/
static enum Granularity {
HOURS, DAYS;
/**
* Publish hourly events. Will include daily events.
*/
HOURS,
/**
* Publish daily events only.
*/
DAYS;
}
private static class ShiftedQuarters {

6
spring-modulith-moments/src/main/java/org/springframework/modulith/moments/support/package-info.java Normal file
View File

@@ -0,0 +1,6 @@
/**
* The {@link org.springframework.modulith.moments.support.Moments} abstraction to integrate with Spring Framework's
* scheduling.
*/
@org.springframework.lang.NonNullApi
package org.springframework.modulith.moments.support;

5
spring-modulith-observability/src/main/java/org/springframework/modulith/observability/autoconfigure/package-info.java Normal file
View File

@@ -0,0 +1,5 @@
/**
* Autoconfiguration for the observability integration.
*/
@org.springframework.lang.NonNullApi
package org.springframework.modulith.observability.autoconfigure;

5
spring-modulith-observability/src/main/java/org/springframework/modulith/observability/package-info.java Normal file
View File

@@ -0,0 +1,5 @@
/**
* Support for application module observability.
*/
@org.springframework.lang.NonNullApi
package org.springframework.modulith.observability;

5
spring-modulith-runtime/src/main/java/org/springframework/modulith/runtime/autoconfigure/package-info.java Normal file
View File

@@ -0,0 +1,5 @@
/**
* Autoconfiguration the {@link org.springframework.modulith.model.ApplicationModules} runtime support.
*/
@org.springframework.lang.NonNullApi
package org.springframework.modulith.runtime.autoconfigure;

5
spring-modulith-runtime/src/main/java/org/springframework/modulith/runtime/package-info.java Normal file
View File

@@ -0,0 +1,5 @@
/**
* Support to run {@link org.springframework.modulith.model.ApplicationModules} at application runtime.
*/
@org.springframework.lang.NonNullApi
package org.springframework.modulith.runtime;

5
spring-modulith-test/src/main/java/org/springframework/modulith/test/package-info.java Normal file
View File

@@ -0,0 +1,5 @@
/**
* Integration test support for Spring Modulith {@link org.springframework.modulith.model.ApplicationModules}.
*/
@org.springframework.lang.NonNullApi
package org.springframework.modulith.test;

10
src/docs/resources/assemblies/docs.xml
View File

@@ -13,6 +13,16 @@
-->
<directory>target/generated-docs</directory>
<outputDirectory>reference</outputDirectory>
<excludes>
<exclude>**/.asciidoctor/**</exclude>
</excludes>
</fileSet>
<fileSet>
<!--
Adds reference manual (html and pdf) to the distribution archive under the 'docs/reference'.
-->
<directory>../target/site/apidocs</directory>
<outputDirectory>api</outputDirectory>
</fileSet>
</fileSets>
</assembly>