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>
 ```