From 9c672deb2d5496fa508c84fd5803efe434c4879d Mon Sep 17 00:00:00 2001 From: Scott Frederick Date: Fri, 16 Oct 2020 17:45:46 -0500 Subject: [PATCH] Add javadoc links in Maven plugin parameter docs This commit modifies the documentation generated for the Maven plugin to include links to javadoc when Spring Boot types are mentioned. Some javadoc was also polished to improve the generated docs. Fixes gh-21555 --- .../mavenplugin/DocumentPluginGoals.java | 36 ++++++++-- .../maven/AbstractDependencyFilterMojo.java | 4 +- .../boot/maven/AbstractPackagerMojo.java | 11 ++-- .../boot/maven/BuildImageMojo.java | 4 +- .../boot/maven/BuildInfoMojo.java | 6 +- .../org/springframework/boot/maven/Image.java | 66 ++++++++++++++----- .../springframework/boot/maven/Layers.java | 4 +- 7 files changed, 93 insertions(+), 38 deletions(-) diff --git a/buildSrc/src/main/java/org/springframework/boot/build/mavenplugin/DocumentPluginGoals.java b/buildSrc/src/main/java/org/springframework/boot/build/mavenplugin/DocumentPluginGoals.java index 9e417954b9c..71191f38da5 100644 --- a/buildSrc/src/main/java/org/springframework/boot/build/mavenplugin/DocumentPluginGoals.java +++ b/buildSrc/src/main/java/org/springframework/boot/build/mavenplugin/DocumentPluginGoals.java @@ -136,11 +136,7 @@ public class DocumentPluginGoals extends DefaultTask { for (Parameter parameter : parameters) { String name = parameter.getName(); writer.printf("| <<%s-%s,%s>>%n", detailsSectionId, name, name); - String type = parameter.getType(); - if (type.lastIndexOf('.') >= 0) { - type = type.substring(type.lastIndexOf('.') + 1); - } - writer.printf("| `%s`%n", type); + writer.printf("| `%s`%n", typeNameToJavadocLink(shortTypeName(parameter.getType()), parameter.getType())); String defaultValue = parameter.getDefaultValue(); if (defaultValue != null) { writer.printf("| `%s`%n", defaultValue); @@ -166,7 +162,7 @@ public class DocumentPluginGoals extends DefaultTask { writer.println("|==="); writer.println(); writeDetail(writer, "Name", name); - writeDetail(writer, "Type", parameter.getType()); + writeDetail(writer, "Type", typeNameToJavadocLink(parameter.getType())); writeOptionalDetail(writer, "Default value", parameter.getDefaultValue()); writeOptionalDetail(writer, "User property", parameter.getUserProperty()); writeOptionalDetail(writer, "Since", parameter.getSince()); @@ -191,4 +187,32 @@ public class DocumentPluginGoals extends DefaultTask { writer.println(); } + private String shortTypeName(String name) { + if (name.lastIndexOf('.') >= 0) { + name = name.substring(name.lastIndexOf('.') + 1); + } + if (name.lastIndexOf('$') >= 0) { + name = name.substring(name.lastIndexOf('$') + 1); + } + return name; + } + + private String typeNameToJavadocLink(String name) { + return typeNameToJavadocLink(name, name); + } + + private String typeNameToJavadocLink(String shortName, String name) { + if (name.startsWith("org.springframework.boot.maven")) { + return "{spring-boot-docs}/maven-plugin/api/" + typeNameToJavadocPath(name) + ".html[" + shortName + "]"; + } + if (name.startsWith("org.springframework.boot")) { + return "{spring-boot-docs}/api/" + typeNameToJavadocPath(name) + ".html[" + shortName + "]"; + } + return shortName; + } + + private String typeNameToJavadocPath(String name) { + return name.replace(".", "/").replace("$", "."); + } + } diff --git a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/main/java/org/springframework/boot/maven/AbstractDependencyFilterMojo.java b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/main/java/org/springframework/boot/maven/AbstractDependencyFilterMojo.java index fb2a08c5c65..c1cf8ffd501 100644 --- a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/main/java/org/springframework/boot/maven/AbstractDependencyFilterMojo.java +++ b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/main/java/org/springframework/boot/maven/AbstractDependencyFilterMojo.java @@ -40,7 +40,7 @@ public abstract class AbstractDependencyFilterMojo extends AbstractMojo { /** * Collection of artifact definitions to include. The {@link Include} element defines - * a {@code groupId} and {@code artifactId} mandatory properties and an optional + * mandatory {@code groupId} and {@code artifactId} properties and an optional * {@code classifier} property. * @since 1.2.0 */ @@ -49,7 +49,7 @@ public abstract class AbstractDependencyFilterMojo extends AbstractMojo { /** * Collection of artifact definitions to exclude. The {@link Exclude} element defines - * a {@code groupId} and {@code artifactId} mandatory properties and an optional + * mandatory {@code groupId} and {@code artifactId} properties and an optional * {@code classifier} property. * @since 1.1.0 */ diff --git a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/main/java/org/springframework/boot/maven/AbstractPackagerMojo.java b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/main/java/org/springframework/boot/maven/AbstractPackagerMojo.java index 94b45034a33..7920c1e3abc 100644 --- a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/main/java/org/springframework/boot/maven/AbstractPackagerMojo.java +++ b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/main/java/org/springframework/boot/maven/AbstractPackagerMojo.java @@ -75,7 +75,7 @@ public abstract class AbstractPackagerMojo extends AbstractDependencyFilterMojo /** * The name of the main class. If not specified the first compiled class found that - * contains a 'main' method will be used. + * contains a {@code main} method will be used. * @since 1.0.0 */ @Parameter @@ -83,8 +83,8 @@ public abstract class AbstractPackagerMojo extends AbstractDependencyFilterMojo /** * The type of archive (which corresponds to how the dependencies are laid out inside - * it). Possible values are JAR, WAR, ZIP, DIR, NONE. Defaults to a guess based on the - * archive type. + * it). Possible values are {@code JAR}, {@code WAR}, {@code ZIP}, {@code DIR}, + * {@code NONE}. Defaults to a guess based on the archive type. * @since 1.0.0 */ @Parameter(property = "spring-boot.repackage.layout") @@ -114,7 +114,8 @@ public abstract class AbstractPackagerMojo extends AbstractDependencyFilterMojo public boolean includeSystemScope; /** - * Layer configuration with the option to exclude layer tools jar. + * Layer configuration with options to disable layer creation, exclude layer tools + * jar, and provide a custom layers configuration file. * @since 2.3.0 */ @Parameter @@ -208,7 +209,7 @@ public abstract class AbstractPackagerMojo extends AbstractDependencyFilterMojo ZIP(new Expanded()), /** - * Dir Layout. + * Directory Layout. */ DIR(new Expanded()), diff --git a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/main/java/org/springframework/boot/maven/BuildImageMojo.java b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/main/java/org/springframework/boot/maven/BuildImageMojo.java index 77ea852f556..eccb047df5e 100644 --- a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/main/java/org/springframework/boot/maven/BuildImageMojo.java +++ b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/main/java/org/springframework/boot/maven/BuildImageMojo.java @@ -98,8 +98,8 @@ public class BuildImageMojo extends AbstractPackagerMojo { private String classifier; /** - * Image configuration, with `builder`, `runImage`, `name`, `env`, `cleanCache` and - * `verboseLogging` options. + * Image configuration, with {@code builder}, {@code runImage}, {@code name}, + * {@code env}, {@code cleanCache} and {@code verboseLogging} options. * @since 2.3.0 */ @Parameter diff --git a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/main/java/org/springframework/boot/maven/BuildInfoMojo.java b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/main/java/org/springframework/boot/maven/BuildInfoMojo.java index ea6d9d16b60..64d6e9adf6e 100644 --- a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/main/java/org/springframework/boot/maven/BuildInfoMojo.java +++ b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/main/java/org/springframework/boot/maven/BuildInfoMojo.java @@ -62,7 +62,7 @@ public class BuildInfoMojo extends AbstractMojo { private MavenProject project; /** - * The location of the generated build-info.properties. + * The location of the generated {@code build-info.properties} file. */ @Parameter(defaultValue = "${project.build.outputDirectory}/META-INF/build-info.properties") private File outputFile; @@ -77,8 +77,8 @@ public class BuildInfoMojo extends AbstractMojo { private String time; /** - * Additional properties to store in the build-info.properties. Each entry is prefixed - * by {@code build.} in the generated build-info.properties. + * Additional properties to store in the {@code build-info.properties} file. Each + * entry is prefixed by {@code build.} in the generated {@code build-info.properties}. */ @Parameter private Map additionalProperties; diff --git a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/main/java/org/springframework/boot/maven/Image.java b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/main/java/org/springframework/boot/maven/Image.java index ada2452471f..c0294b3cbe3 100644 --- a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/main/java/org/springframework/boot/maven/Image.java +++ b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/main/java/org/springframework/boot/maven/Image.java @@ -37,48 +37,78 @@ import org.springframework.util.StringUtils; */ public class Image { - /** - * The name of the created image. - */ String name; - /** - * The builder used to create the image. - */ String builder; - /** - * The run image used to launch the built image. - */ String runImage; - /** - * Environment properties that should be passed to the builder. - */ Map env; - /** - * If the cache should be cleaned before building. - */ boolean cleanCache; - /** - * If verbose logging is required. - */ boolean verboseLogging; + /** + * The name of the created image. + * @return the image name + */ + public String getName() { + return this.name; + } + void setName(String name) { this.name = name; } + /** + * The name of the builder image to use to create the image. + * @return the builder image name + */ + public String getBuilder() { + return this.builder; + } + void setBuilder(String builder) { this.builder = builder; } + /** + * The name of the run image to use to create the image. + * @return the builder image name + */ + public String getRunImage() { + return this.runImage; + } + void setRunImage(String runImage) { this.runImage = runImage; } + /** + * Environment properties that should be passed to the builder. + * @return the environment properties + */ + public Map getEnv() { + return this.env; + } + + /** + * If the cache should be cleaned before building. + * @return {@code true} if the cache should be cleaned + */ + public boolean isCleanCache() { + return this.cleanCache; + } + + /** + * If verbose logging is required. + * @return {@code true} for verbose logging + */ + public boolean isVerboseLogging() { + return this.verboseLogging; + } + BuildRequest getBuildRequest(Artifact artifact, Function applicationContent) { return customize(BuildRequest.of(getOrDeduceName(artifact), applicationContent)); } diff --git a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/main/java/org/springframework/boot/maven/Layers.java b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/main/java/org/springframework/boot/maven/Layers.java index a3d253863b4..10dfc389778 100644 --- a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/main/java/org/springframework/boot/maven/Layers.java +++ b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/main/java/org/springframework/boot/maven/Layers.java @@ -33,8 +33,8 @@ public class Layers { private File configuration; /** - * Whether a layers.idx file should be added to the jar. - * @return true if a layers.idx file should be added. + * Whether a {@code layers.idx} file should be added to the jar. + * @return true if a {@code layers.idx} file should be added. */ public boolean isEnabled() { return this.enabled;