Skip to content
This repository was archived by the owner on Dec 19, 2023. It is now read-only.

Commit b0b2242

Browse files
jmisurjmisur
authored
Generic support for field/method tags (#156)
1 parent 1de0c89 commit b0b2242

File tree

15 files changed

+198
-52
lines changed

15 files changed

+198
-52
lines changed

‎spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/javadoc/ClassJavadoc.java‎

Lines changed: 40 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -23,40 +23,53 @@
2323

2424
class ClassJavadoc {
2525
private String comment;
26-
private Map<String, String> fields = new HashMap<>();
26+
private Map<String, FieldJavadoc> fields = new HashMap<>();
2727
private Map<String, MethodJavadoc> methods = new HashMap<>();
2828

2929
public String getClassComment() {
3030
return comment;
3131
}
3232

3333
public String getFieldComment(String fieldName) {
34-
return trimToEmpty(fields.get(fieldName));
34+
FieldJavadoc fieldJavadoc = fields.get(fieldName);
35+
if (fieldJavadoc != null) {
36+
return trimToEmpty(fieldJavadoc.getComment());
37+
} else {
38+
return "";
39+
}
3540
}
3641

3742
public String getMethodComment(String methodName) {
3843
MethodJavadoc methodJavadoc = methods.get(methodName);
3944
if (methodJavadoc != null) {
40-
return methodJavadoc.getComment();
45+
return trimToEmpty(methodJavadoc.getComment());
4146
} else {
4247
return "";
4348
}
4449
}
4550

46-
public String getMethodTitle(String methodName) {
51+
public String getMethodParameterComment(String methodName, String parameterName) {
4752
MethodJavadoc methodJavadoc = methods.get(methodName);
48-
4953
if (methodJavadoc != null) {
50-
return methodJavadoc.getTitle();
54+
return trimToEmpty(methodJavadoc.getParameterComment(parameterName));
5155
} else {
5256
return "";
5357
}
5458
}
5559

56-
public String getMethodParameterComment(String methodName, String parameterName) {
57-
MethodJavadoc methodJavadoc = methods.get(methodName);
60+
public String getMethodTag(String javaMethodName, String tagName) {
61+
MethodJavadoc methodJavadoc = methods.get(javaMethodName);
5862
if (methodJavadoc != null) {
59-
return methodJavadoc.getParameterComment(parameterName);
63+
return trimToEmpty(methodJavadoc.getTag(tagName));
64+
} else {
65+
return "";
66+
}
67+
}
68+
69+
public String getFieldTag(String javaFieldName, String tagName) {
70+
FieldJavadoc fieldJavadoc = fields.get(javaFieldName);
71+
if (fieldJavadoc != null) {
72+
return trimToEmpty(fieldJavadoc.getTag(tagName));
6073
} else {
6174
return "";
6275
}
@@ -67,20 +80,33 @@ private static String trimToEmpty(String value) {
6780
}
6881

6982
static class MethodJavadoc {
70-
private String title;
7183
private String comment;
7284
private Map<String, String> parameters = new HashMap<>();
85+
private Map<String, String> tags = new HashMap<>();
7386

7487
public String getComment() {
75-
return trimToEmpty(comment);
88+
return comment;
7689
}
7790

7891
public String getParameterComment(String parameterName) {
79-
return trimToEmpty(parameters.get(parameterName));
92+
return parameters.get(parameterName);
93+
}
94+
95+
public String getTag(String tagName) {
96+
return tags.get(tagName);
97+
}
98+
}
99+
100+
static class FieldJavadoc {
101+
private String comment;
102+
private Map<String, String> tags = new HashMap<>();
103+
104+
public String getComment() {
105+
return comment;
80106
}
81107

82-
public String getTitle() {
83-
return trimToEmpty(title);
108+
public String getTag(String tagName) {
109+
return tags.get(tagName);
84110
}
85111
}
86112
}

‎spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/javadoc/JavadocReader.java‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,10 +19,12 @@
1919
public interface JavadocReader {
2020
String resolveFieldComment(Class<?> javaBaseClass, String javaFieldName);
2121

22-
String resolveMethodComment(Class<?> javaBaseClass, String javaMethodName);
22+
String resolveFieldTag(Class<?> javaBaseClass, String javaFieldName, String tagName);
2323

24-
String resolveMethodTitle(Class<?> javaBaseClass, String javaMethodName);
24+
String resolveMethodComment(Class<?> javaBaseClass, String javaMethodName);
2525

2626
String resolveMethodParameterComment(Class<?> javaBaseClass, String javaMethodName,
2727
String javaParameterName);
28+
29+
String resolveMethodTag(Class<?> javaBaseClass, String javaMethodName, String tagName);
2830
}

‎spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/javadoc/JavadocReaderImpl.java‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -77,13 +77,13 @@ public String resolveFieldComment(Class<?> javaBaseClass, String javaFieldName)
7777
}
7878

7979
@Override
80-
public String resolveMethodComment(Class<?> javaBaseClass, String javaMethodName) {
81-
return classJavadoc(javaBaseClass).getMethodComment(javaMethodName);
80+
public String resolveFieldTag(Class<?> javaBaseClass, String javaFieldName, String tagName) {
81+
return classJavadoc(javaBaseClass).getFieldTag(javaFieldName, tagName);
8282
}
8383

8484
@Override
85-
public String resolveMethodTitle(Class<?> javaBaseClass, String javaMethodName) {
86-
return classJavadoc(javaBaseClass).getMethodTitle(javaMethodName);
85+
public String resolveMethodComment(Class<?> javaBaseClass, String javaMethodName) {
86+
return classJavadoc(javaBaseClass).getMethodComment(javaMethodName);
8787
}
8888

8989
@Override
@@ -93,6 +93,11 @@ public String resolveMethodParameterComment(Class<?> javaBaseClass, String javaM
9393
.getMethodParameterComment(javaMethodName, javaParameterName);
9494
}
9595

96+
@Override
97+
public String resolveMethodTag(Class<?> javaBaseClass, String javaMethodName, String tagName) {
98+
return classJavadoc(javaBaseClass).getMethodTag(javaMethodName, tagName);
99+
}
100+
96101
private ClassJavadoc classJavadoc(Class<?> clazz) {
97102
String relativePath = classToRelativePath(clazz);
98103
ClassJavadoc classJavadocFromCache = classCache.get(relativePath);

‎spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/section/SectionSnippet.java‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -113,8 +113,8 @@ private Map<String, Object> defaultModel(Operation operation) {
113113
}
114114

115115
private String resolveTitle(HandlerMethod handlerMethod, JavadocReader javadocReader) {
116-
String title = javadocReader.resolveMethodTitle(handlerMethod.getBeanType(),
117-
handlerMethod.getMethod().getName());
116+
String title = javadocReader.resolveMethodTag(handlerMethod.getBeanType(),
117+
handlerMethod.getMethod().getName(), "title");
118118
if (StringUtils.isBlank(title)) {
119119
title = createTitle(handlerMethod.getMethod().getName());
120120
}

‎spring-auto-restdocs-core/src/test/java/capital/scalable/restdocs/javadoc/JavadocReaderImplIntegrationTest.java‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,14 +30,17 @@ public void resolveComments() {
3030
String comment = javadocReader.resolveFieldComment(IntegrationType.class, "usefulField");
3131
assertThat(comment, equalTo("Very useful field"));
3232

33+
comment = javadocReader.resolveFieldTag(IntegrationType.class, "usefulField", "see");
34+
assertThat(comment, equalTo("other useful fields"));
35+
3336
comment = javadocReader.resolveMethodComment(IntegrationType.class, "dummyMethod");
3437
// line breaks are not handled here - pure javadoc
3538
assertThat(comment, equalTo("Very useful method<br>\n with new line"));
3639

37-
comment = javadocReader.resolveMethodTitle(IntegrationType.class, "dummyMethod");
40+
comment = javadocReader.resolveMethodTag(IntegrationType.class, "dummyMethod", "title");
3841
assertThat(comment, equalTo("My Dummy Method"));
3942

40-
comment = javadocReader.resolveMethodTitle(IntegrationType.class, "dummyMethod2");
43+
comment = javadocReader.resolveMethodComment(IntegrationType.class, "dummyMethod2");
4144
assertThat(comment, equalTo(""));
4245

4346
comment = javadocReader.resolveMethodParameterComment(IntegrationType.class, "dummyMethod",
@@ -52,6 +55,8 @@ public void resolveComments() {
5255
static class IntegrationType {
5356
/**
5457
* Very useful field
58+
*
59+
* @see other useful fields
5560
*/
5661
private String usefulField;
5762

‎spring-auto-restdocs-core/src/test/java/capital/scalable/restdocs/javadoc/JavadocReaderImplTest.java‎

Lines changed: 34 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,22 @@ public void resolveFieldCommentAcrossDirectories() {
5252
assertThat(comment, equalTo("Simple field comment"));
5353
}
5454

55+
@Test
56+
public void resolveFieldTag() {
57+
JavadocReader javadocReader = JavadocReaderImpl.createWith(SOURCE_DIR);
58+
String comment = javadocReader.resolveFieldTag(SimpleType.class, "simpleField",
59+
"deprecated");
60+
assertThat(comment, equalTo("Deprecation comment"));
61+
}
62+
63+
@Test
64+
public void resolveFieldTagFromClasspath() {
65+
JavadocReader javadocReader = JavadocReaderImpl.createWith(null);
66+
String comment = javadocReader.resolveFieldTag(SimpleType.class, "simpleField",
67+
"deprecated");
68+
assertThat(comment, equalTo("Deprecation comment from classpath"));
69+
}
70+
5571
@Test
5672
public void resolveMethodComment() {
5773
JavadocReader javadocReader = JavadocReaderImpl.createWith(SOURCE_DIR);
@@ -67,16 +83,16 @@ public void resolveMethodCommentFromClasspath() {
6783
}
6884

6985
@Test
70-
public void resolveMethodTitle() {
86+
public void resolveMethodTag() {
7187
JavadocReader javadocReader = JavadocReaderImpl.createWith(SOURCE_DIR);
72-
String comment = javadocReader.resolveMethodTitle(SimpleType.class, "simpleMethod");
88+
String comment = javadocReader.resolveMethodTag(SimpleType.class, "simpleMethod", "title");
7389
assertThat(comment, equalTo("Simple method title"));
7490
}
7591

7692
@Test
77-
public void resolveMethodTitleFromClasspath() {
93+
public void resolveMethodTagFromClasspath() {
7894
JavadocReader javadocReader = JavadocReaderImpl.createWith(null);
79-
String comment = javadocReader.resolveMethodTitle(SimpleType.class, "simpleMethod");
95+
String comment = javadocReader.resolveMethodTag(SimpleType.class, "simpleMethod", "title");
8096
assertThat(comment, equalTo("Simple method title from classpath"));
8197
}
8298

@@ -103,9 +119,15 @@ public void jsonFileDoesNotExist() {
103119
// json file for class does not exist
104120
String comment = javadocReader.resolveFieldComment(NotExisting.class, "simpleField2");
105121
assertThat(comment, is(""));
122+
comment = javadocReader.resolveFieldTag(NotExisting.class, "simpleField", "tag");
123+
assertThat(comment, is(""));
124+
comment = javadocReader.resolveFieldTag(NotExisting.class, "simpleField2", "tag");
125+
assertThat(comment, is(""));
106126
comment = javadocReader.resolveMethodComment(NotExisting.class, "simpleMethod");
107127
assertThat(comment, is(""));
108-
comment = javadocReader.resolveMethodTitle(NotExisting.class, "simpleMethod");
128+
comment = javadocReader.resolveMethodTag(NotExisting.class, "simpleMethod", "tag");
129+
assertThat(comment, is(""));
130+
comment = javadocReader.resolveMethodTag(NotExisting.class, "simpleMethod2", "tag");
109131
assertThat(comment, is(""));
110132
comment = javadocReader.resolveMethodParameterComment(NotExisting.class, "simpleMethod",
111133
"simpleParameter");
@@ -119,9 +141,15 @@ public void jsonNotDocumented() {
119141
// json file exists but field/method/parameter is not present
120142
String comment = javadocReader.resolveFieldComment(SimpleType.class, "simpleField2");
121143
assertThat(comment, is(""));
144+
comment = javadocReader.resolveFieldTag(SimpleType.class, "simpleField", "tag");
145+
assertThat(comment, is(""));
146+
comment = javadocReader.resolveFieldTag(SimpleType.class, "simpleField2", "tag");
147+
assertThat(comment, is(""));
122148
comment = javadocReader.resolveMethodComment(SimpleType.class, "simpleMethod2");
123149
assertThat(comment, is(""));
124-
comment = javadocReader.resolveMethodTitle(SimpleType.class, "simpleMethod2");
150+
comment = javadocReader.resolveMethodTag(SimpleType.class, "simpleMethod", "tag");
151+
assertThat(comment, is(""));
152+
comment = javadocReader.resolveMethodTag(SimpleType.class, "simpleMethod2", "tag");
125153
assertThat(comment, is(""));
126154
comment = javadocReader.resolveMethodParameterComment(SimpleType.class, "simpleMethod",
127155
"simpleParameter2");

‎spring-auto-restdocs-core/src/test/java/capital/scalable/restdocs/section/SectionSnippetTest.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -219,7 +219,7 @@ public void customTitle() throws Exception {
219219

220220

221221
private void mockMethodTitle(Class<?> javaBaseClass, String methodName, String title) {
222-
when(javadocReader.resolveMethodTitle(javaBaseClass, methodName))
222+
when(javadocReader.resolveMethodTag(javaBaseClass, methodName, "title"))
223223
.thenReturn(title);
224224
}
225225

‎spring-auto-restdocs-core/src/test/resources/capital/scalable/restdocs/javadoc/JavadocReaderImplTest.SimpleType.json‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,21 @@
11
{
22
"fields": {
3-
"simpleField": "Simple field comment from classpath"
3+
"simpleField": {
4+
"comment": "Simple field comment from classpath",
5+
"tags": {
6+
"deprecated": "Deprecation comment from classpath"
7+
}
8+
}
49
},
510
"methods": {
611
"simpleMethod": {
7-
"title": "Simple method title from classpath",
812
"comment": "Simple method comment from classpath",
913
"parameters": {
1014
"simpleParameter": "Simple parameter comment from classpath"
15+
},
16+
"tags": {
17+
"title": "Simple method title from classpath",
18+
"deprecated": "Deprecation comment from classpath"
1119
}
1220
}
1321
}

‎spring-auto-restdocs-core/src/test/resources/json/capital/scalable/restdocs/javadoc/JavadocReaderImplTest.SimpleType.json‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,21 @@
11
{
22
"fields": {
3-
"simpleField": "Simple field comment"
3+
"simpleField": {
4+
"comment": "Simple field comment",
5+
"tags": {
6+
"deprecated": "Deprecation comment"
7+
}
8+
}
49
},
510
"methods": {
611
"simpleMethod": {
7-
"title": "Simple method title",
812
"comment": "Simple method comment",
913
"parameters": {
1014
"simpleParameter": "Simple parameter comment"
15+
},
16+
"tags": {
17+
"title": "Simple method title",
18+
"deprecated": "Deprecation comment"
1119
}
1220
}
1321
}

‎spring-auto-restdocs-json-doclet/src/main/java/capital/scalable/restdocs/jsondoclet/ClassDocumentation.java‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@
2525

2626
public final class ClassDocumentation {
2727
private String comment = "";
28-
private final Map<String, String> fields = new HashMap<>();
28+
private final Map<String, FieldDocumentation> fields = new HashMap<>();
2929
private final Map<String, MethodDocumentation> methods = new HashMap<>();
3030

3131
private ClassDocumentation() {
@@ -36,7 +36,7 @@ public static ClassDocumentation fromClassDoc(ClassDoc classDoc) {
3636
ClassDocumentation cd = new ClassDocumentation();
3737
cd.setComment(classDoc.commentText());
3838
for (FieldDoc fieldDoc : classDoc.fields(false)) {
39-
cd.addField(fieldDoc.name(), fieldDoc.commentText());
39+
cd.addField(fieldDoc);
4040
}
4141
for (MethodDoc methodDoc : classDoc.methods(false)) {
4242
cd.addMethod(methodDoc);
@@ -48,8 +48,8 @@ private void setComment(String comment) {
4848
this.comment = comment;
4949
}
5050

51-
private void addField(String name, String comment) {
52-
this.fields.put(name, comment);
51+
private void addField(FieldDoc fieldDoc) {
52+
this.fields.put(fieldDoc.name(), FieldDocumentation.fromFieldDoc(fieldDoc));
5353
}
5454

5555
private void addMethod(MethodDoc methodDoc) {

0 commit comments

Comments
 (0)