flag to format JavaDoc for Palantir formatter (#2009 fixes #1995)

Author: nedtwigg

CHANGES.md

@@ -12,6 +12,7 @@ We adhere to the [keepachangelog](https://keepachangelog.com/en/1.0.0/) format (
 ## [Unreleased]
 ### Added
 * Maven - Support for formatting shell scripts via [shfmt](https://github.com/mvdan/sh). ([#1998](https://github.com/diffplug/spotless/pull/1998))
+* Maven / Gradle - Support for formatting Java Docs for the Palantir formatter ([#2009](https://github.com/diffplug/spotless/pull/2009))
 
 ## [2.44.0] - 2024-01-15
 ### Added

CONTRIBUTING.md

@@ -171,6 +171,17 @@ gradlew :plugin-maven:test --tests com.diffplug.spotless.maven.pom.SortPomMavenT
 gradlew :plugin-gradle:test --tests com.diffplug.gradle.spotless.FreshMarkExtensionTest
 ```
 
+## Check and format code
+
+Before creating a pull request, you might want to format (yes, spotless is  formatted by spotless)
+the code and check for possible bugs
+
+* `./gradlew spotlessApply`
+* `./gradlew spotbugsMain`
+
+These checks are also run by the automated pipeline when you submit a pull request, if
+the pipeline fails, first check if the code is formatted and no bugs were found.
+
 ## Integration testing
 
 ### Gradle - locally

lib/src/main/java/com/diffplug/spotless/java/PalantirJavaFormatStep.java

@@ -27,6 +27,7 @@ public class PalantirJavaFormatStep {
 	// prevent direct instantiation
 	private PalantirJavaFormatStep() {}
 
+	private static final boolean DEFAULT_FORMAT_JAVADOC = false;
 	private static final String DEFAULT_STYLE = "PALANTIR";
 	private static final String NAME = "palantir-java-format";
 	public static final String MAVEN_COORDINATE = "com.palantir.javaformat:palantir-java-format:";
@@ -42,14 +43,25 @@ public static FormatterStep create(String version, Provisioner provisioner) {
 		return create(version, defaultStyle(), provisioner);
 	}
 
-	/** Creates a step which formats everything - code, import order, and unused imports. And with the style input. */
+	/**
+	 * Creates a step which formats code, import order, and unused imports, but not Java docs. And with the given format
+	 * style.
+	 */
 	public static FormatterStep create(String version, String style, Provisioner provisioner) {
+		return create(version, style, DEFAULT_FORMAT_JAVADOC, provisioner);
+	}
+
+	/**
+	 * Creates a step which formats everything - code, import order, unused imports, and Java docs. And with the given
+	 * format style.
+	 */
+	public static FormatterStep create(String version, String style, boolean formatJavadoc, Provisioner provisioner) {
 		Objects.requireNonNull(version, "version");
 		Objects.requireNonNull(style, "style");
 		Objects.requireNonNull(provisioner, "provisioner");
 
 		return FormatterStep.createLazy(NAME,
-				() -> new State(JarState.from(MAVEN_COORDINATE + version, provisioner), version, style),
+				() -> new State(JarState.from(MAVEN_COORDINATE + version, provisioner), version, style, formatJavadoc),
 				State::createFormat);
 	}
 
@@ -63,6 +75,11 @@ public static String defaultStyle() {
 		return DEFAULT_STYLE;
 	}
 
+	/** Get default for whether Java docs should be formatted */
+	public static boolean defaultFormatJavadoc() {
+		return DEFAULT_FORMAT_JAVADOC;
+	}
+
 	private static final class State implements Serializable {
 		private static final long serialVersionUID = 1L;
 
@@ -71,23 +88,23 @@ private static final class State implements Serializable {
 		/** Version of the formatter jar. */
 		private final String formatterVersion;
 		private final String style;
+		/** Whether to format Java docs. */
+		private final boolean formatJavadoc;
 
-		State(JarState jarState, String formatterVersion) {
-			this(jarState, formatterVersion, DEFAULT_STYLE);
-		}
-
-		State(JarState jarState, String formatterVersion, String style) {
+		State(JarState jarState, String formatterVersion, String style, boolean formatJavadoc) {
 			ModuleHelper.doOpenInternalPackagesIfRequired();
 			this.jarState = jarState;
 			this.formatterVersion = formatterVersion;
 			this.style = style;
+			this.formatJavadoc = formatJavadoc;
 		}
 
 		FormatterFunc createFormat() throws Exception {
 			final ClassLoader classLoader = jarState.getClassLoader();
 			final Class<?> formatterFunc = classLoader.loadClass("com.diffplug.spotless.glue.pjf.PalantirJavaFormatFormatterFunc");
-			final Constructor<?> constructor = formatterFunc.getConstructor(String.class); // style
-			return JVM_SUPPORT.suggestLaterVersionOnError(formatterVersion, (FormatterFunc) constructor.newInstance(style));
+			// 1st arg is "style", 2nd arg is "formatJavadoc"
+			final Constructor<?> constructor = formatterFunc.getConstructor(String.class, boolean.class);
+			return JVM_SUPPORT.suggestLaterVersionOnError(formatterVersion, (FormatterFunc) constructor.newInstance(style, formatJavadoc));
 		}
 	}
 }

lib/src/palantirJavaFormat/java/com/diffplug/spotless/glue/pjf/PalantirJavaFormatFormatterFunc.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2022-2023 DiffPlug
+ * Copyright 2022-2024 DiffPlug
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -15,6 +15,9 @@
  */
 package com.diffplug.spotless.glue.pjf;
 
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+
 import com.palantir.javaformat.java.Formatter;
 import com.palantir.javaformat.java.ImportOrderer;
 import com.palantir.javaformat.java.JavaFormatterOptions;
@@ -28,11 +31,20 @@ public class PalantirJavaFormatFormatterFunc implements FormatterFunc {
 
 	private final JavaFormatterOptions.Style formatterStyle;
 
-	public PalantirJavaFormatFormatterFunc(String style) {
+	/**
+	 * Creates a new formatter func that formats code via Palantir.
+	 * @param style The style to use for formatting.
+	 * @param formatJavadoc Whether to format Java docs. Requires at least Palantir 2.36.0 or later, otherwise the
+	 * constructor will throw.
+	 */
+	public PalantirJavaFormatFormatterFunc(String style, boolean formatJavadoc) {
 		this.formatterStyle = JavaFormatterOptions.Style.valueOf(style);
-		formatter = Formatter.createFormatter(JavaFormatterOptions.builder()
-				.style(formatterStyle)
-				.build());
+		JavaFormatterOptions.Builder builder = JavaFormatterOptions.builder();
+		builder.style(formatterStyle);
+		if (formatJavadoc) {
+			applyFormatJavadoc(builder);
+		}
+		formatter = Formatter.createFormatter(builder.build());
 	}
 
 	@Override
@@ -47,4 +59,15 @@ public String apply(String input) throws Exception {
 	public String toString() {
 		return "PalantirJavaFormatFormatterFunc{formatter=" + formatter + '}';
 	}
+
+	private static void applyFormatJavadoc(JavaFormatterOptions.Builder builder) {
+		// The formatJavadoc option is available since Palantir 2.36.0
+		// To support older versions for now, attempt to invoke the builder method via reflection.
+		try {
+			Method formatJavadoc = JavaFormatterOptions.Builder.class.getMethod("formatJavadoc", boolean.class);
+			formatJavadoc.invoke(builder, true);
+		} catch (NoSuchMethodException | InvocationTargetException | IllegalAccessException e) {
+			throw new IllegalStateException("Cannot enable formatJavadoc option, make sure you are using Palantir with version 2.36.0 or later", e);
+		}
+	}
 }

plugin-gradle/CHANGES.md

@@ -4,6 +4,9 @@ We adhere to the [keepachangelog](https://keepachangelog.com/en/1.0.0/) format (
 
 ## [Unreleased]
 
+### Added
+* Maven / Gradle - Support for formatting Java Docs for the Palantir formatter ([#2009](https://github.com/diffplug/spotless/pull/2009))
+
 ## [6.24.0] - 2024-01-15
 ### Added
 * Support for shell formatting via [shfmt](https://github.com/mvdan/sh). ([#1994](https://github.com/diffplug/spotless/pull/1994))

plugin-gradle/README.md

@@ -220,6 +220,8 @@ spotless {
     palantirJavaFormat()
     // optional: you can specify a specific version and/or switch to AOSP/GOOGLE style
     palantirJavaFormat('2.9.0').style("GOOGLE")
+    // optional: you can also format Javadocs, requires at least Palantir 2.39.0
+    palantirJavaFormat('2.39.0').formatJavadoc(true)
 ```
 
 ### eclipse jdt

plugin-gradle/src/main/java/com/diffplug/gradle/spotless/JavaExtension.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016-2023 DiffPlug
+ * Copyright 2016-2024 DiffPlug
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -256,6 +256,7 @@ public PalantirJavaFormatConfig palantirJavaFormat(String version) {
 	public class PalantirJavaFormatConfig {
 		final String version;
 		String style;
+		boolean formatJavadoc;
 
 		PalantirJavaFormatConfig(String version) {
 			this.version = Objects.requireNonNull(version);
@@ -269,8 +270,14 @@ public PalantirJavaFormatConfig style(String style) {
 			return this;
 		}
 
+		public PalantirJavaFormatConfig formatJavadoc(boolean formatJavadoc) {
+			this.formatJavadoc = formatJavadoc;
+			replaceStep(createStep());
+			return this;
+		}
+
 		private FormatterStep createStep() {
-			return PalantirJavaFormatStep.create(version, style, provisioner());
+			return PalantirJavaFormatStep.create(version, style, formatJavadoc, provisioner());
 		}
 	}
 

plugin-gradle/src/test/java/com/diffplug/gradle/spotless/PalantirJavaFormatIntegrationTest.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2022 DiffPlug
+ * Copyright 2022-2024 DiffPlug
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -45,4 +45,26 @@ void integration() throws IOException {
 				"palantirJavaFormat('1.0.1')");
 		checkRunsThenUpToDate();
 	}
+
+	@Test
+	void formatJavaDoc() throws IOException {
+		setFile("build.gradle").toLines(
+				"plugins {",
+				"    id 'com.diffplug.spotless'",
+				"}",
+				"repositories { mavenCentral() }",
+				"",
+				"spotless {",
+				"    java {",
+				"        target file('test.java')",
+				"        palantirJavaFormat('2.39.0').formatJavadoc(true)",
+				"    }",
+				"}");
+
+		setFile("test.java").toResource("java/palantirjavaformat/JavaCodeWithJavaDocUnformatted.test");
+		gradleRunner().withArguments("spotlessApply").build();
+		assertFile("test.java").sameAsResource("java/palantirjavaformat/JavaCodeWithJavaDocFormatted.test");
+
+		checkRunsThenUpToDate();
+	}
 }

plugin-maven/CHANGES.md

@@ -5,6 +5,7 @@ We adhere to the [keepachangelog](https://keepachangelog.com/en/1.0.0/) format (
 ## [Unreleased]
 ### Added
 * Support for formatting shell scripts via [shfmt](https://github.com/mvdan/sh). ([#1998](https://github.com/diffplug/spotless/issues/1998))
+* Maven / Gradle - Support for formatting Java Docs for the Palantir formatter ([#2009](https://github.com/diffplug/spotless/pull/2009))
 
 ## [2.42.0] - 2024-01-15
 ### Added

plugin-maven/README.md

@@ -246,8 +246,9 @@ any other maven phase (i.e. compile) then it can be configured as below;
 
 ```xml
 <palantirJavaFormat>
-  <version>2.10.0</version>                     <!-- optional -->
+  <version>2.39.0</version>                     <!-- optional -->
   <style>PALANTIR</style>                       <!-- or AOSP/GOOGLE (optional) -->
+  <formatJavadoc>false</formatJavadoc>          <!-- defaults to false (optional, requires at least Palantir 2.39.0) -->
 </palantirJavaFormat>
 ```