Skip to content

Commit 93a8d6c

Browse files
simschlasimschla
committed
feat: add format-annotations step
1 parent 0810e76 commit 93a8d6c

8 files changed

Lines changed: 430 additions & 3 deletions

File tree

‎README.md‎

Lines changed: 54 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -149,8 +149,10 @@ or apply the formatting to the files.
149149
150150
Available formatting steps:
151151
clang-format Runs clang-format
152-
license-header Runs license header
152+
format-annotations Corrects line break formatting of type annotations in
153+
java files.
153154
google-java-format Runs google java format
155+
license-header Runs license header
154156
palantir-java-format Runs palantir java format
155157
prettier Runs prettier, the opinionated code formatter.
156158
@@ -177,6 +179,7 @@ Possible exit codes:
177179
Spotless CLI supports the following formatter steps in alphabetical order:
178180

179181
- [clang-format](#clang-format)
182+
- [format-annotations](#format-annotations)
180183
- [google-java-format](#google-java-format)
181184
- [license-header](#license-header)
182185
- [palantir-java-format](#palantir-java-format)
@@ -220,6 +223,56 @@ spotless --target '**/src/**/*.cpp' clang-format --clang-version=20.1.2 --style=
220223
> [!IMPORTANT]
221224
> Running a clang-format step requires a working installation of the clang-format binary.
222225
226+
### format-annotations
227+
228+
TODO: maybe list possible target file types - maybe in the shields?
229+
230+
In Java, type annotations should be on the same line as the type that they qualify. This formatter fixes this for you.
231+
232+
To see usage instructions for the format-annotations formatter, run: `spotless format-annotations --help`
233+
234+
<!---freshmark usage_format_annotations
235+
output =
236+
'```\n' +
237+
{{usage.format-annotations.array}}.join('\n') +
238+
'\n```';
239+
-->
240+
241+
```
242+
Usage: spotless format-annotations [-hV] [-a[=annotation[,
243+
annotation...]...]]... [-r[=annotation[,
244+
annotation...]...]]...
245+
Corrects line break formatting of type annotations in java files.
246+
-a, --add-type-annotation[=annotation[,annotation...]...]
247+
Add annotations to the list of type annotations to keep on
248+
the same line as the type.
249+
-h, --help Show this help message and exit.
250+
-r, --remove-type-annotation[=annotation[,annotation...]...]
251+
Remove annotations from the list of type annotations to keep
252+
on the same line as the type.
253+
-V, --version Print version information and exit.
254+
```
255+
256+
<!---freshmark /usage_format_annotations -->
257+
258+
Example usage:
259+
260+
```shell
261+
spotless --target '**/src/**/*.java' format-annotations
262+
263+
# or add/remove annotations to the default set using list syntax
264+
spotless --target '**/src/**/*.java' format-annotations \
265+
--add-type-annotation='MyAnnotation1,MyAnnotation2' \
266+
--remove-type-annotation='MyAnnotation3,MyAnnotation4'
267+
268+
# or add/remove annotations to the default set using repeated options
269+
spotless --target '**/src/**/*.java' format-annotations \
270+
--add-type-annotation='MyAnnotation1' \
271+
--add-type-annotation='MyAnnotation2' \
272+
--remove-type-annotation='MyAnnotation3' \
273+
--remove-type-annotation='MyAnnotation4'
274+
```
275+
223276
### google-java-format
224277

225278
<!---freshmark gjfshields

‎app/src/main/java/com/diffplug/spotless/cli/steps/FormatAnnotations.java‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
/*
2+
* Copyright 2025 DiffPlug
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
package com.diffplug.spotless.cli.steps;
17+
18+
import java.nio.file.Path;
19+
import java.util.List;
20+
21+
import org.jetbrains.annotations.NotNull;
22+
23+
import com.diffplug.spotless.FormatterStep;
24+
import com.diffplug.spotless.cli.help.OptionConstants;
25+
import com.diffplug.spotless.cpp.ClangFormatStep;
26+
27+
import picocli.CommandLine;
28+
29+
@CommandLine.Command(name = "clang-format", description = "Runs clang-format")
30+
public class ClangFormat extends SpotlessFormatterStep {
31+
32+
@CommandLine.Option(
33+
names = {"--clang-version", "-v"},
34+
required = true,
35+
defaultValue = "10.0.1",
36+
description = "The version of clang-format to use." + OptionConstants.DEFAULT_VALUE_SUFFIX)
37+
String version;
38+
39+
@CommandLine.Option(
40+
names = {"--clang-format-exec", "-c"},
41+
description = "The path to the clang-format executable." + OptionConstants.DEFAULT_VALUE_SUFFIX_BEGIN
42+
+ "looks on your PATH" + OptionConstants.DEFAULT_VALUE_SUFFIX_END)
43+
Path pathToExec;
44+
45+
@CommandLine.Option(
46+
names = {"--style", "-s"},
47+
description = "The style to use for clang-format.")
48+
String style;
49+
50+
@Override
51+
public @NotNull List<FormatterStep> prepareFormatterSteps() {
52+
ClangFormatStep clangFormatStep = ClangFormatStep.withVersion(version);
53+
if (pathToExec != null) {
54+
clangFormatStep = clangFormatStep.withPathToExe(pathToExec.toString());
55+
}
56+
if (style != null) {
57+
clangFormatStep = clangFormatStep.withStyle(style);
58+
}
59+
return List.of(clangFormatStep.create());
60+
}
61+
}

‎app/src/test/java/com/diffplug/spotless/cli/steps/FormatAnnotationsTest.java‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
/*
2+
* Copyright 2025 DiffPlug
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
package com.diffplug.spotless.cli.steps;
17+
18+
import org.junit.jupiter.api.Test;
19+
20+
import com.diffplug.spotless.cli.CLIIntegrationHarness;
21+
22+
public class FormatAnnotationsTest extends CLIIntegrationHarness {
23+
24+
@Test
25+
void itFormatsAnnotations() {
26+
setFile("Test.java").toResource("java/formatannotations/FormatAnnotationsTestInput.test");
27+
28+
cliRunner().withTargets("Test.java").withStep(FormatAnnotations.class).run();
29+
30+
assertFile("Test.java").notSameSasResource("java/formatannotations/FormatAnnotationsTestInput.test");
31+
selfie().expectResource("Test.java").toMatchDisk();
32+
}
33+
34+
@Test
35+
void itHandlesAnnotationsInComments() {
36+
setFile("Test.java").toResource("java/formatannotations/FormatAnnotationsInCommentsInput.test");
37+
38+
cliRunner().withTargets("Test.java").withStep(FormatAnnotations.class).run();
39+
40+
assertFile("Test.java").notSameSasResource("java/formatannotations/FormatAnnotationsInCommentsInput.test");
41+
selfie().expectResource("Test.java").toMatchDisk();
42+
}
43+
44+
@Test
45+
void itWorksWithAddingAndRemovingCommentsAsRepeatedOption() {
46+
setFile("Test.java").toResource("java/formatannotations/FormatAnnotationsAddRemoveInput.test");
47+
48+
cliRunner()
49+
.withTargets("Test.java")
50+
.withStep(FormatAnnotations.class)
51+
.withOption("--add-type-annotation", "Empty")
52+
.withOption("--add-type-annotation", "NonEmpty")
53+
.withOption("--remove-type-annotation", "Localized")
54+
.run();
55+
56+
assertFile("Test.java").notSameSasResource("java/formatannotations/FormatAnnotationsAddRemoveInput.test");
57+
selfie().expectResource("Test.java").toMatchDisk();
58+
}
59+
60+
@Test
61+
void itWorksWithAddingAndRemovingCommentsAsSingleOption() {
62+
setFile("Test.java").toResource("java/formatannotations/FormatAnnotationsAddRemoveInput.test");
63+
64+
cliRunner()
65+
.withTargets("Test.java")
66+
.withStep(FormatAnnotations.class)
67+
.withOption("--add-type-annotation", "Empty,NonEmpty")
68+
.withOption("--remove-type-annotation", "Localized")
69+
.run();
70+
71+
assertFile("Test.java").notSameSasResource("java/formatannotations/FormatAnnotationsAddRemoveInput.test");
72+
selfie().expectResource("Test.java").toMatchDisk();
73+
}
74+
}

‎app/src/test/resources/com/diffplug/spotless/cli/steps/FormatAnnotationsTest.ss‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
╔═ itFormatsAnnotations ═╗
2+
class FormatAnnotationsTest {
3+
4+
public @Nullable String s0 = null;
5+
6+
@Deprecated
7+
public @Nullable String m0() {}
8+
9+
@Nullable String s1 = null;
10+
11+
@Deprecated
12+
@Nullable String m1() {}
13+
14+
@Nullable @Deprecated
15+
String m2() {}
16+
17+
@Nullable @Regex(2) @Interned String s2 = null;
18+
19+
@Deprecated
20+
@Nullable @Regex(2) @Interned String m3() {}
21+
22+
@Nullable @Deprecated
23+
@Regex(2) @Interned String m4() {}
24+
25+
@Nullable
26+
// a comment
27+
@Regex(2) @Interned String s3 = null;
28+
29+
@Nullable // a comment
30+
@Regex(2) @Interned String s4 = null;
31+
32+
@Nullable @Regex(2) @Interned
33+
// a comment
34+
String s5 = null;
35+
36+
@Deprecated
37+
// a comment
38+
@Nullable @Regex(2) @Interned String m5() {}
39+
40+
@Deprecated
41+
@Nullable
42+
// a comment
43+
@Regex(2) @Interned String m6() {}
44+
45+
@Empty
46+
String e;
47+
48+
@NonEmpty
49+
String ne;
50+
51+
@Localized String localized;
52+
}
53+
54+
@Deprecated
55+
@SuppressWarnings
56+
public
57+
@Interned @MustCall("close") class MyClass1 {
58+
// No body
59+
}
60+
61+
╔═ itHandlesAnnotationsInComments ═╗
62+
class FormatAnnotationsInComments {
63+
64+
// Here is a comment
65+
@Interned String m1() {}
66+
67+
// Here is another comment
68+
String m2() {}
69+
70+
/**
71+
* Here is a misformatted type annotation within a Javadoc comment.
72+
*
73+
* @Nullable
74+
* String s;
75+
*/
76+
77+
@Nullable @Interned String m3(/* Don't get confused by other comments on the line with the type */) {}
78+
79+
@Nullable @Interned String m3() {} // Still not confused
80+
81+
/*
82+
code snippets in regular comments do get re-formatted
83+
84+
@Nullable String s;
85+
*/
86+
}
87+
88+
╔═ itWorksWithAddingAndRemovingCommentsAsRepeatedOption ═╗
89+
class FormatAnnotationsAddRemove {
90+
91+
@Empty String e;
92+
93+
@NonEmpty String ne;
94+
95+
@Localized
96+
String localized;
97+
}
98+
99+
╔═ itWorksWithAddingAndRemovingCommentsAsSingleOption ═╗
100+
class FormatAnnotationsAddRemove {
101+
102+
@Empty String e;
103+
104+
@NonEmpty String ne;
105+
106+
@Localized
107+
String localized;
108+
}
109+
110+
╔═ [end of file] ═╗

‎build-logic/src/main/groovy/com/diffplug/spotless/cli/picocli/usage/DocumentedUsages.groovy‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ package com.diffplug.spotless.cli.picocli.usage
33
enum DocumentedUsages {
44

55
CLANG_FORMAT(),
6+
FORMAT_ANNOTATIONS(),
67
MAIN(""),
78
GOOGLE_JAVA_FORMAT(),
89
LICENSE_HEADER(),
@@ -13,11 +14,11 @@ enum DocumentedUsages {
1314

1415
private final String formatterStepName
1516

16-
DocumentedUsages(){
17+
DocumentedUsages() {
1718
this(null)
1819
}
1920

20-
DocumentedUsages(String formatterStepName){
21+
DocumentedUsages(String formatterStepName) {
2122
this.formatterStepName = formatterStepName ?: name().toLowerCase().replace('_', '-')
2223
this.fileName = "${name().toLowerCase().replace('_', '-')}.spotless.usage.txt"
2324
}

‎testlib/src/main/resources/java/formatannotations/FormatAnnotationsAddRemoveInput.test‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
class FormatAnnotationsAddRemove {
2+
3+
@Empty
4+
String e;
5+
6+
@NonEmpty
7+
String ne;
8+
9+
@Localized
10+
String localized;
11+
}

‎testlib/src/main/resources/java/formatannotations/FormatAnnotationsInCommentsInput.test‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
class FormatAnnotationsInComments {
2+
3+
// Here is a comment
4+
@Interned
5+
String m1() {}
6+
7+
// Here is another comment
8+
String m2() {}
9+
10+
/**
11+
* Here is a misformatted type annotation within a Javadoc comment.
12+
*
13+
* @Nullable
14+
* String s;
15+
*/
16+
17+
@Nullable
18+
@Interned
19+
String m3(/* Don't get confused by other comments on the line with the type */) {}
20+
21+
@Nullable
22+
@Interned
23+
String m3() {} // Still not confused
24+
25+
/*
26+
code snippets in regular comments do get re-formatted
27+
28+
@Nullable
29+
String s;
30+
*/
31+
}

0 commit comments

Comments
 (0)