Review Maven build Javadoc

initializr-generator/src/main/java/io/spring/initializr/generator/buildsystem/maven/MavenBuild.java

@@ -18,10 +18,11 @@ package io.spring.initializr.generator.buildsystem.maven;
 
 import io.spring.initializr.generator.buildsystem.Build;
 import io.spring.initializr.generator.buildsystem.BuildItemResolver;
+import io.spring.initializr.generator.buildsystem.MavenRepositoryContainer;
 import io.spring.initializr.generator.buildsystem.maven.MavenBuildSettings.Builder;
 
 /**
- * Maven build for a project.
+ * Maven-specific {@linkplain Build build configuration}.
  *
  * @author Andy Wilkinson
  * @author Stephane Nicoll
@@ -54,14 +55,29 @@ public class MavenBuild extends Build {
 		return this.settings.build();
 	}
 
+	/**
+	 * Return the {@linkplain MavenResource resource container} to use to configure main
+	 * resources.
+	 * @return the {@link MavenRepositoryContainer} for main resources
+	 */
 	public MavenResourceContainer resources() {
 		return this.resources;
 	}
 
+	/**
+	 * Return the {@linkplain MavenResource resource container} to use to configure test
+	 * resources.
+	 * @return the {@link MavenRepositoryContainer} for test resources
+	 */
 	public MavenResourceContainer testResources() {
 		return this.testResources;
 	}
 
+	/**
+	 * Return the {@linkplain MavenPluginContainer plugin container} to use to configure
+	 * plugins.
+	 * @return the {@link MavenPluginContainer}
+	 */
 	public MavenPluginContainer plugins() {
 		return this.plugins;
 	}

initializr-generator/src/main/java/io/spring/initializr/generator/buildsystem/maven/MavenBuildSettings.java

@@ -17,6 +17,7 @@
 package io.spring.initializr.generator.buildsystem.maven;
 
 import io.spring.initializr.generator.buildsystem.BuildSettings;
+import io.spring.initializr.generator.packaging.Packaging;
 
 /**
  * Maven {@link BuildSettings}.
@@ -121,35 +122,78 @@ public class MavenBuildSettings extends BuildSettings {
 		public Builder() {
 		}
 
+		/**
+		 * Set the coordinates of the project.
+		 * @param groupId the group ID of the project
+		 * @param artifactId the artifact ID of the project
+		 * @return this for method chaining
+		 */
 		public Builder coordinates(String groupId, String artifactId) {
 			return group(groupId).artifact(artifactId);
 		}
 
+		/**
+		 * Set the coordinates of the parent.
+		 * @param groupId the groupID of the parent
+		 * @param artifactId the artifactID of the parent
+		 * @param version the version of the parent
+		 * @return this for method chaining
+		 */
 		public Builder parent(String groupId, String artifactId, String version) {
 			this.parent = new MavenParent(groupId, artifactId, version);
 			return self();
 		}
 
+		/**
+		 * Set the packaging of the project.
+		 * @param packaging the packaging
+		 * @return this for method chaining
+		 * @see Packaging
+		 */
 		public Builder packaging(String packaging) {
 			this.packaging = packaging;
 			return self();
 		}
 
+		/**
+		 * Set the name of the project.
+		 * @param name the name of the project
+		 * @return this for method chaining
+		 */
 		public Builder name(String name) {
 			this.name = name;
 			return self();
 		}
 
+		/**
+		 * Set a human readable description of the project.
+		 * @param description the description of the project
+		 * @return this for method chaining
+		 */
 		public Builder description(String description) {
 			this.description = description;
 			return self();
 		}
 
+		/**
+		 * Set the the location of main source code. Can use Maven properties such as
+		 * {@code ${basedir}}.
+		 * @param sourceDirectory the location of main source code or {@code null} to use
+		 * the default
+		 * @return this for method chaining
+		 */
 		public Builder sourceDirectory(String sourceDirectory) {
 			this.sourceDirectory = sourceDirectory;
 			return self();
 		}
 
+		/**
+		 * Set the the location of test source code. Can use Maven properties such as
+		 * {@code ${basedir}}.
+		 * @param testSourceDirectory the location of test source code or {@code null} to
+		 * use the default
+		 * @return this for method chaining
+		 */
 		public Builder testSourceDirectory(String testSourceDirectory) {
 			this.testSourceDirectory = testSourceDirectory;
 			return self();

initializr-generator/src/main/java/io/spring/initializr/generator/buildsystem/maven/MavenBuildWriter.java

@@ -42,7 +42,7 @@ import io.spring.initializr.generator.version.VersionProperty;
 import io.spring.initializr.generator.version.VersionReference;
 
 /**
- * A {@link MavenBuild} writer.
+ * A {@link MavenBuild} writer for {@code pom.xml}.
  *
  * @author Andy Wilkinson
  * @author Stephane Nicoll
@@ -50,6 +50,13 @@ import io.spring.initializr.generator.version.VersionReference;
  */
 public class MavenBuildWriter {
 
+	/**
+	 * Write a {@linkplain MavenBuild pom.xml} using the specified
+	 * {@linkplain IndentingWriter writer}.
+	 * @param writer the writer to use
+	 * @param build the maven build to write
+	 * @throws IOException if the writer fails to write the build
+	 */
 	public void writeTo(IndentingWriter writer, MavenBuild build) throws IOException {
 		MavenBuildSettings settings = build.getSettings();
 		writeProject(writer, () -> {

initializr-generator/src/main/java/io/spring/initializr/generator/buildsystem/maven/MavenDependency.java

@@ -19,7 +19,7 @@ package io.spring.initializr.generator.buildsystem.maven;
 import io.spring.initializr.generator.buildsystem.Dependency;
 
 /**
- * A {@link Dependency} with specific settings for the Maven build system.
+ * Maven-specific {@link Dependency}.
  *
  * @author Stephane Nicoll
  */
@@ -32,14 +32,30 @@ public class MavenDependency extends Dependency {
 		this.optional = builder.optional;
 	}
 
+	/**
+	 * Initialize a new dependency {@link Builder} with the specified coordinates.
+	 * @param groupId the group ID of the dependency
+	 * @param artifactId the artifact ID of the dependency
+	 * @return a new builder
+	 */
 	public static Builder withCoordinates(String groupId, String artifactId) {
 		return new Builder(groupId, artifactId);
 	}
 
+	/**
+	 * Initialize a new dependency {@link Builder} with the state of the specified
+	 * {@link Dependency}.
+	 * @param dependency the dependency to use to initialize the builder
+	 * @return a new builder initialized with the same state as the {@code dependency}
+	 */
 	public static Builder from(Dependency dependency) {
 		return new Builder(dependency.getGroupId(), dependency.getArtifactId()).initialize(dependency);
 	}
 
+	/**
+	 * Return whether this dependency is {@code optional}.
+	 * @return {@code true} if the dependency is optional
+	 */
 	public boolean isOptional() {
 		return this.optional;
 	}
@@ -57,6 +73,11 @@ public class MavenDependency extends Dependency {
 			super(groupId, artifactId);
 		}
 
+		/**
+		 * Specify if the dependency is {@code optional}.
+		 * @param optional whether the dependency is optional
+		 * @return this for method chaining
+		 */
 		public Builder optional(boolean optional) {
 			this.optional = optional;
 			return self();

initializr-generator/src/main/java/io/spring/initializr/generator/buildsystem/maven/MavenParent.java

@@ -35,14 +35,26 @@ public class MavenParent {
 		this.version = version;
 	}
 
+	/**
+	 * Return the group ID of the parent.
+	 * @return the group ID
+	 */
 	public String getGroupId() {
 		return this.groupId;
 	}
 
+	/**
+	 * Return the artifact ID of the parent.
+	 * @return the artifact ID
+	 */
 	public String getArtifactId() {
 		return this.artifactId;
 	}
 
+	/**
+	 * Return the version of the parent.
+	 * @return the version
+	 */
 	public String getVersion() {
 		return this.version;
 	}

initializr-generator/src/main/java/io/spring/initializr/generator/buildsystem/maven/MavenPlugin.java

@@ -57,30 +57,59 @@ public class MavenPlugin {
 		this.configuration = (builder.configurationBuilder == null) ? null : builder.configurationBuilder.build();
 	}
 
+	/**
+	 * Return the group ID of the plugin.
+	 * @return the group ID
+	 */
 	public String getGroupId() {
 		return this.groupId;
 	}
 
+	/**
+	 * Return the artifact ID of the plugin.
+	 * @return the artifact ID
+	 */
 	public String getArtifactId() {
 		return this.artifactId;
 	}
 
+	/**
+	 * Return the version of the plugin or {@code null} if the version of the plugin is
+	 * managed.
+	 * @return the version or {@code null}
+	 */
 	public String getVersion() {
 		return this.version;
 	}
 
+	/**
+	 * Return whether to load extensions of this plugin.
+	 * @return {@code true} to load extensions
+	 */
 	public boolean isExtensions() {
 		return this.extensions;
 	}
 
+	/**
+	 * Return the {@linkplain Execution executions} of the plugin.
+	 * @return the executions
+	 */
 	public List<Execution> getExecutions() {
 		return this.executions;
 	}
 
+	/**
+	 * Return the {@linkplain Dependency dependencies} of the plugin.
+	 * @return the dependencies
+	 */
 	public List<Dependency> getDependencies() {
 		return this.dependencies;
 	}
 
+	/**
+	 * Return the {@linkplain Configuration configuration} of the plugin.
+	 * @return the configuration
+	 */
 	public Configuration getConfiguration() {
 		return this.configuration;
 	}
@@ -104,39 +133,74 @@ public class MavenPlugin {
 
 		private ConfigurationBuilder configurationBuilder;
 
-		public Builder(String groupId, String artifactId) {
+		protected Builder(String groupId, String artifactId) {
 			this.groupId = groupId;
 			this.artifactId = artifactId;
 		}
 
+		/**
+		 * Set the version of the plugin or {@code null} if the version is managed by the
+		 * project.
+		 * @param version the version of the plugin or {@code null}
+		 * @return this for method chaining
+		 */
 		public Builder version(String version) {
 			this.version = version;
 			return this;
 		}
 
-		public Builder extensions() {
-			this.extensions = true;
+		/**
+		 * Set whether to load extensions of this plugin.
+		 * @param extensions whether to load extensions
+		 * @return this for method chaining
+		 */
+		public Builder extensions(boolean extensions) {
+			this.extensions = extensions;
 			return this;
 		}
 
-		public Builder configuration(Consumer<ConfigurationBuilder> consumer) {
+		/**
+		 * Customize the {@code configuration} of the plugin using the specified consumer.
+		 * @param configuration a consumer of the current configuration
+		 * @return this for method chaining
+		 */
+		public Builder configuration(Consumer<ConfigurationBuilder> configuration) {
 			if (this.configurationBuilder == null) {
 				this.configurationBuilder = new ConfigurationBuilder();
 			}
-			consumer.accept(this.configurationBuilder);
+			configuration.accept(this.configurationBuilder);
 			return this;
 		}
 
-		public Builder execution(String id, Consumer<ExecutionBuilder> customizer) {
-			customizer.accept(this.executions.computeIfAbsent(id, (key) -> new ExecutionBuilder(id)));
+		/**
+		 * Add an {@code execution} with the specified id and {@link Consumer} to
+		 * customize the object. If the execution has already been¬ added, the consumer
+		 * can be used to further tune the existing plugin execution
+		 * @param id the id of the execution
+		 * @param execution a {@link Consumer} to customize the {@link Execution}
+		 * @return this for method chaining
+		 */
+		public Builder execution(String id, Consumer<ExecutionBuilder> execution) {
+			execution.accept(this.executions.computeIfAbsent(id, (key) -> new ExecutionBuilder(id)));
 			return this;
 		}
 
+		/**
+		 * Add a plugin dependency.
+		 * @param groupId the group ID of the dependency
+		 * @param artifactId the artifact ID of the dependency
+		 * @param version the version of the dependency
+		 * @return this for method chaining
+		 */
 		public Builder dependency(String groupId, String artifactId, String version) {
 			this.dependencies.add(new Dependency(groupId, artifactId, version));
 			return this;
 		}
 
+		/**
+		 * Build a {@link MavenPlugin} with the current state of this builder.
+		 * @return a {@link MavenBuild}
+		 */
 		public MavenPlugin build() {
 			return new MavenPlugin(this);
 		}
@@ -165,21 +229,38 @@ public class MavenPlugin {
 					(this.configurationCustomization == null) ? null : this.configurationCustomization.build());
 		}
 
+		/**
+		 * Set the {@code phase} of the build lifecycle that goals will execute in.
+		 * @param phase the phase to use
+		 * @return this for method chaining
+		 */
 		public ExecutionBuilder phase(String phase) {
 			this.phase = phase;
 			return this;
 		}
 
+		/**
+		 * Add a goal to invoke for this execution.
+		 * @param goal the goal to invoke
+		 * @return this for method chaining
+		 */
 		public ExecutionBuilder goal(String goal) {
 			this.goals.add(goal);
 			return this;
 		}
 
-		public void configuration(Consumer<ConfigurationBuilder> consumer) {
+		/**
+		 * Customize the {@code configuration} of the execution using the specified
+		 * consumer.
+		 * @param configuration a consumer of the current configuration
+		 * @return this for method chaining
+		 */
+		public ExecutionBuilder configuration(Consumer<ConfigurationBuilder> configuration) {
 			if (this.configurationCustomization == null) {
 				this.configurationCustomization = new ConfigurationBuilder();
 			}
-			consumer.accept(this.configurationCustomization);
+			configuration.accept(this.configurationCustomization);
+			return this;
 		}
 
 	}
@@ -226,6 +307,10 @@ public class MavenPlugin {
 			return this;
 		}
 
+		/**
+		 * Build a {@link Configuration} with the current state of this builder.
+		 * @return a {@link Configuration}
+		 */
 		Configuration build() {
 			return new Configuration(this.settings.stream().map((entry) -> resolve(entry.getName(), entry.getValue()))
 					.collect(Collectors.toList()));
@@ -255,6 +340,10 @@ public class MavenPlugin {
 			this.settings = Collections.unmodifiableList(settings);
 		}
 
+		/**
+		 * Return the {@linkplain Setting settings} of the configuration.
+		 * @return the settings
+		 */
 		public List<Setting> getSettings() {
 			return this.settings;
 		}
@@ -275,10 +364,18 @@ public class MavenPlugin {
 			this.value = value;
 		}
 
+		/**
+		 * Return the name of the configuration item.
+		 * @return the name
+		 */
 		public String getName() {
 			return this.name;
 		}
 
+		/**
+		 * Return the value. Can be a nested {@link Configuration}.
+		 * @return a simple value or a nested configuration
+		 */
 		public Object getValue() {
 			return this.value;
 		}
@@ -305,18 +402,34 @@ public class MavenPlugin {
 			this.configuration = configuration;
 		}
 
+		/**
+		 * Return the id of the execution.
+		 * @return the execution id
+		 */
 		public String getId() {
 			return this.id;
 		}
 
+		/**
+		 * Return the {@code phase} of the build lifecycle that goals will execute in.
+		 * @return the execution phase
+		 */
 		public String getPhase() {
 			return this.phase;
 		}
 
+		/**
+		 * Return the plugin gaols that this execution should invoke.
+		 * @return the execution goals
+		 */
 		public List<String> getGoals() {
 			return this.goals;
 		}
 
+		/**
+		 * Return the {@linkplain Configuration configuration} of the execution.
+		 * @return the configuration
+		 */
 		public Configuration getConfiguration() {
 			return this.configuration;
 		}
@@ -340,14 +453,26 @@ public class MavenPlugin {
 			this.version = version;
 		}
 
+		/**
+		 * Return the group ID of the plugin dependency.
+		 * @return the group ID
+		 */
 		public String getGroupId() {
 			return this.groupId;
 		}
 
+		/**
+		 * Return the artifact ID of the plugin dependency.
+		 * @return the artifact ID
+		 */
 		public String getArtifactId() {
 			return this.artifactId;
 		}
 
+		/**
+		 * Return the version of the plugin dependency.
+		 * @return the version
+		 */
 		public String getVersion() {
 			return this.version;
 		}

initializr-generator/src/main/java/io/spring/initializr/generator/buildsystem/maven/MavenResource.java

@@ -64,7 +64,7 @@ public class MavenResource {
 	}
 
 	/**
-	 * Specify if filtering is enabled when copying resources.
+	 * Return whether filtering is enabled when copying resources.
 	 * @return {@code true} if filtering is enabled
 	 */
 	public boolean isFiltering() {
@@ -109,26 +109,53 @@ public class MavenResource {
 			this.directory = directory;
 		}
 
+		/**
+		 * Set the directory structure to place the set of resources from a build or
+		 * {@code null} to use the root directory.
+		 * @param targetPath the target path
+		 * @return this for method chaining
+		 */
 		public Builder targetPath(String targetPath) {
 			this.targetPath = targetPath;
 			return this;
 		}
 
+		/**
+		 * Specify if filtering is enabled when copying resources.
+		 * @param filtering {@code true} to enable resource filtering
+		 * @return this for method chaining
+		 */
 		public Builder filtering(Boolean filtering) {
 			this.filtering = filtering;
 			return this;
 		}
 
+		/**
+		 * Set the files patterns to use to include files. In conflicts between
+		 * {@code include} and {@code exclude}, {@code exclude} wins.
+		 * @param includes the include patterns
+		 * @return this for method chaining
+		 */
 		public Builder includes(String... includes) {
 			this.includes = Arrays.asList(includes);
 			return this;
 		}
 
+		/**
+		 * Set the files patterns to use to exclude files. In conflicts between
+		 * {@code include} and {@code exclude}, {@code exclude} wins.
+		 * @param excludes the exclude patterns
+		 * @return this for method chaining
+		 */
 		public Builder excludes(String... excludes) {
 			this.excludes = Arrays.asList(excludes);
 			return this;
 		}
 
+		/**
+		 * Build a {@link MavenResource} with the current state of this builder.
+		 * @return a {@link MavenResource}
+		 */
 		public MavenResource build() {
 			return new MavenResource(this);
 		}

initializr-generator/src/test/java/io/spring/initializr/generator/buildsystem/maven/MavenBuildTests.java

@@ -16,7 +16,6 @@
 
 package io.spring.initializr.generator.buildsystem.maven;
 
-import io.spring.initializr.generator.buildsystem.maven.MavenPlugin.Builder;
 import org.junit.jupiter.api.Test;
 
 import static org.assertj.core.api.Assertions.assertThat;
@@ -135,7 +134,7 @@ class MavenBuildTests {
 	@Test
 	void mavenPluginExtensionsCanBeLoaded() {
 		MavenBuild build = new MavenBuild();
-		build.plugins().add("com.example", "test-plugin", Builder::extensions);
+		build.plugins().add("com.example", "test-plugin", (plugin) -> plugin.extensions(true));
 		assertThat(build.plugins().values())
 				.hasOnlyOneElementSatisfying((testPlugin) -> assertThat(testPlugin.isExtensions()).isTrue());
 	}

initializr-generator/src/test/java/io/spring/initializr/generator/buildsystem/maven/MavenBuildWriterTests.java

@@ -442,7 +442,7 @@ class MavenBuildWriterTests {
 	void pomWithPluginWithExtensions() throws Exception {
 		MavenBuild build = new MavenBuild();
 		build.settings().coordinates("com.example.demo", "demo");
-		build.plugins().add("com.example.demo", "demo-plugin", MavenPlugin.Builder::extensions);
+		build.plugins().add("com.example.demo", "demo-plugin", (plugin) -> plugin.extensions(true));
 		generatePom(build, (pom) -> {
 			NodeAssert plugin = pom.nodeAtPath("/project/build/plugins/plugin");
 			assertThat(plugin).textAtPath("groupId").isEqualTo("com.example.demo");