diff --git a/CHANGES.md b/CHANGES.md
index e13eed2745..a94d20dd09 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -11,8 +11,8 @@ 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))
* Support for `gofmt` ([#2001](https://github.com/diffplug/spotless/pull/2001))
+* Support for formatting Java Docs for the Palantir formatter ([#2009](https://github.com/diffplug/spotless/pull/2009))
## [2.44.0] - 2024-01-15
### Added
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 6fb993f419..f0a4b4d59c 100644
--- a/CONTRIBUTING.md
+++ b/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
diff --git a/lib/src/main/java/com/diffplug/spotless/java/PalantirJavaFormatStep.java b/lib/src/main/java/com/diffplug/spotless/java/PalantirJavaFormatStep.java
index 95f7b355f7..a670a6fea7 100644
--- a/lib/src/main/java/com/diffplug/spotless/java/PalantirJavaFormatStep.java
+++ b/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));
}
}
}
diff --git a/lib/src/palantirJavaFormat/java/com/diffplug/spotless/glue/pjf/PalantirJavaFormatFormatterFunc.java b/lib/src/palantirJavaFormat/java/com/diffplug/spotless/glue/pjf/PalantirJavaFormatFormatterFunc.java
index 189bbb54be..bdec215435 100644
--- a/lib/src/palantirJavaFormat/java/com/diffplug/spotless/glue/pjf/PalantirJavaFormatFormatterFunc.java
+++ b/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);
+ }
+ }
}
diff --git a/plugin-gradle/CHANGES.md b/plugin-gradle/CHANGES.md
index b712a4e3d8..ac5be538c7 100644
--- a/plugin-gradle/CHANGES.md
+++ b/plugin-gradle/CHANGES.md
@@ -5,6 +5,9 @@ We adhere to the [keepachangelog](https://keepachangelog.com/en/1.0.0/) format (
## [Unreleased]
* Support for `gofmt` ([#2001](https://github.com/diffplug/spotless/pull/2001))
+### 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))
diff --git a/plugin-gradle/README.md b/plugin-gradle/README.md
index 730a947d49..e80d143653 100644
--- a/plugin-gradle/README.md
+++ b/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
@@ -1086,16 +1088,34 @@ To apply prettier to more kinds of files, just add more formats
Since spotless uses the actual npm prettier package behind the scenes, it is possible to use prettier with
[plugins](https://prettier.io/docs/en/plugins.html#official-plugins) or [community-plugins](https://www.npmjs.com/search?q=prettier-plugin) in order to support even more file types.
+#### prettier version below 3
+
```gradle
spotless {
java {
prettier(['prettier': '2.8.8', 'prettier-plugin-java': '2.2.0']).config(['parser': 'java', 'tabWidth': 4])
- // prettier(['prettier': '3.0.3', 'prettier-plugin-java': '2.3.0']).config(['parser': 'java', 'tabWidth': 4, 'plugins': ['prettier-plugin-java']]) // Prettier v3 requires additional 'plugins' config
}
format 'php', {
target 'src/**/*.php'
prettier(['prettier': '2.8.8', '@prettier/plugin-php': '0.19.6']).config(['parser': 'php', 'tabWidth': 3])
- // prettier(['prettier': '3.0.3', '@prettier/plugin-php': '0.20.1']).config(['parser': 'php', 'tabWidth': 3, 'plugins': ['@prettier/plugin-php']]) // Prettier v3 requires additional 'plugins' config
+ }
+}
+```
+
+#### prettier version 3+
+
+With version 3 prettier it is required to pass in an additional 'plugins' parameter to the config block with a list of plugins you want to use.
+
+```gradle
+spotless {
+ java {
+ prettier(['prettier': '3.0.3', 'prettier-plugin-java': '2.3.0'])
+ .config(['parser': 'java', 'tabWidth': 4, 'plugins': ['prettier-plugin-java']])
+ }
+ format 'php', {
+ target 'src/**/*.php'
+ prettier(['prettier': '3.0.3', '@prettier/plugin-php': '0.20.1'])
+ .config(['parser': 'php', 'tabWidth': 3, 'plugins': ['@prettier/plugin-php']])
}
}
```
diff --git a/plugin-gradle/src/main/java/com/diffplug/gradle/spotless/JavaExtension.java b/plugin-gradle/src/main/java/com/diffplug/gradle/spotless/JavaExtension.java
index bb24a716cd..db869dc4e6 100644
--- a/plugin-gradle/src/main/java/com/diffplug/gradle/spotless/JavaExtension.java
+++ b/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());
}
}
diff --git a/plugin-gradle/src/test/java/com/diffplug/gradle/spotless/PalantirJavaFormatIntegrationTest.java b/plugin-gradle/src/test/java/com/diffplug/gradle/spotless/PalantirJavaFormatIntegrationTest.java
index 2283ce34bf..9990039cd3 100644
--- a/plugin-gradle/src/test/java/com/diffplug/gradle/spotless/PalantirJavaFormatIntegrationTest.java
+++ b/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();
+ }
}
diff --git a/plugin-maven/CHANGES.md b/plugin-maven/CHANGES.md
index b7dd430f8e..d1f158d533 100644
--- a/plugin-maven/CHANGES.md
+++ b/plugin-maven/CHANGES.md
@@ -6,6 +6,7 @@ We adhere to the [keepachangelog](https://keepachangelog.com/en/1.0.0/) format (
### Added
* Support for formatting shell scripts via [shfmt](https://github.com/mvdan/sh). ([#1998](https://github.com/diffplug/spotless/issues/1998))
* Support for `gofmt` ([#2001](https://github.com/diffplug/spotless/pull/2001))
+* Support for formatting Java Docs for the Palantir formatter ([#2009](https://github.com/diffplug/spotless/pull/2009))
## [2.42.0] - 2024-01-15
### Added
diff --git a/plugin-maven/README.md b/plugin-maven/README.md
index 47ee6b5d37..97128768d9 100644
--- a/plugin-maven/README.md
+++ b/plugin-maven/README.md
@@ -247,8 +247,9 @@ any other maven phase (i.e. compile) then it can be configured as below;
```xml
Care for more details? + * + *