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

Commit 7547e0d

Browse files
jmisurjmisur
authored
section title (#129)
1 parent b492dab commit 7547e0d

File tree

18 files changed

+254
-29
lines changed

18 files changed

+254
-29
lines changed

‎docs/index.html‎

Lines changed: 41 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1097,7 +1097,7 @@ <h3 id="snippets-section"><a class="link" href="#snippets-section">Section snipp
10971097
<tr>
10981098
<td class="tableblock halign-left valign-top"><p class="tableblock">{title}</p></td>
10991099
<td class="tableblock halign-left valign-top"><p class="tableblock">Get Item By Id</p></td>
1100-
<td class="tableblock halign-left valign-top"><p class="tableblock">Derived from method name. For example: <code>getItemById</code>.</p></td>
1100+
<td class="tableblock halign-left valign-top"><p class="tableblock">See <a href="#snippets-customization-title">Section title</a>.</p></td>
11011101
</tr>
11021102
<tr>
11031103
<td class="tableblock halign-left valign-top"><p class="tableblock">{snippets}</p></td>
@@ -1188,7 +1188,9 @@ <h4 id="snippets-section-configuration"><a class="link" href="#snippets-section-
11881188
</table>
11891189
</div>
11901190
<div class="sect3">
1191-
<h4 id="_customisation_options"><a class="link" href="#_customisation_options">Customisation options</a></h4>
1191+
<h4 id="snippets-customization"><a class="link" href="#snippets-customization">Customisation options</a></h4>
1192+
<div class="sect4">
1193+
<h5 id="snippets-customization-order"><a class="link" href="#snippets-customization-order">Sections and order</a></h5>
11921194
<div class="paragraph">
11931195
<p>If you want to configure custom sections and their order, instead of using <code>AutoDocumentation.section()</code> you can use
11941196
<code>AutoDocumentation.sectionBuilder()</code> in the following manner:</p>
@@ -1218,6 +1220,42 @@ <h4 id="_customisation_options"><a class="link" href="#_customisation_options">C
12181220
</tr>
12191221
</table>
12201222
</div>
1223+
</div>
1224+
<div class="sect4">
1225+
<h5 id="snippets-customization-title"><a class="link" href="#snippets-customization-title">Section title</a></h5>
1226+
<div class="paragraph">
1227+
<p>Section title uses text from <code>@title</code> Javadoc tag on the handler method.
1228+
If missing, it&#8217;s derived from the method name, e.g. <code>getItemById</code> &#8594; <em>Get Item By Id</em>.</p>
1229+
</div>
1230+
<div class="paragraph">
1231+
<p>If you use <code>@title</code> tag and want to generate regular Javadoc we well,
1232+
you need to include this tag among custom tags in plugin configuration.</p>
1233+
</div>
1234+
<div class="listingblock">
1235+
<div class="title">Custom maven-javadoc-plugin configuration</div>
1236+
<div class="content">
1237+
<pre class="highlightjs highlight"><code class="language-xml" data-lang="xml">&lt;plugin&gt;
1238+
&lt;artifactId&gt;maven-javadoc-plugin&lt;/artifactId&gt;
1239+
&lt;executions&gt;
1240+
&lt;execution&gt;
1241+
&lt;id&gt;attach-javadocs&lt;/id&gt;
1242+
&lt;goals&gt;
1243+
&lt;goal&gt;jar&lt;/goal&gt;
1244+
&lt;/goals&gt;
1245+
&lt;configuration&gt;
1246+
&lt;tags&gt;
1247+
&lt;tag&gt;
1248+
&lt;name&gt;title&lt;/name&gt;
1249+
&lt;placement&gt;m&lt;/placement&gt;
1250+
&lt;/tag&gt;
1251+
&lt;/tags&gt;
1252+
&lt;/configuration&gt;
1253+
&lt;/execution&gt;
1254+
&lt;/executions&gt;
1255+
&lt;/plugin&gt;</code></pre>
1256+
</div>
1257+
</div>
1258+
</div>
12211259
</div>
12221260
</div>
12231261
<div class="sect2">
@@ -1486,7 +1524,7 @@ <h4 id="contributing-building-build"><a class="link" href="#contributing-buildin
14861524
</div>
14871525
<div id="footer">
14881526
<div id="footer-text">
1489-
Last updated 2017-07-31 20:33:00 CEST
1527+
Last updated 2017-08-19 17:44:51 CEST
14901528
</div>
14911529
</div>
14921530
<link rel="stylesheet" href="highlight/styles/github.min.css">

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

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,16 @@ public String getMethodComment(String methodName) {
4343
}
4444
}
4545

46+
public String getMethodTitle(String methodName) {
47+
MethodJavadoc methodJavadoc = methods.get(methodName);
48+
49+
if (methodJavadoc != null) {
50+
return methodJavadoc.getTitle();
51+
} else {
52+
return "";
53+
}
54+
}
55+
4656
public String getMethodParameterComment(String methodName, String parameterName) {
4757
MethodJavadoc methodJavadoc = methods.get(methodName);
4858
if (methodJavadoc != null) {
@@ -57,6 +67,7 @@ private static String trimToEmpty(String value) {
5767
}
5868

5969
static class MethodJavadoc {
70+
private String title;
6071
private String comment;
6172
private Map<String, String> parameters = new HashMap<>();
6273

@@ -67,5 +78,9 @@ public String getComment() {
6778
public String getParameterComment(String parameterName) {
6879
return trimToEmpty(parameters.get(parameterName));
6980
}
81+
82+
public String getTitle() {
83+
return trimToEmpty(title);
84+
}
7085
}
7186
}

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,8 @@ public interface JavadocReader {
2121

2222
String resolveMethodComment(Class<?> javaBaseClass, String javaMethodName);
2323

24+
String resolveMethodTitle(Class<?> javaBaseClass, String javaMethodName);
25+
2426
String resolveMethodParameterComment(Class<?> javaBaseClass, String javaMethodName,
2527
String javaParameterName);
2628
}

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

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,11 @@ public String resolveMethodComment(Class<?> javaBaseClass, String javaMethodName
7070
return classJavadoc(javaBaseClass).getMethodComment(javaMethodName);
7171
}
7272

73+
@Override
74+
public String resolveMethodTitle(Class<?> javaBaseClass, String javaMethodName) {
75+
return classJavadoc(javaBaseClass).getMethodTitle(javaMethodName);
76+
}
77+
7378
@Override
7479
public String resolveMethodParameterComment(Class<?> javaBaseClass, String javaMethodName,
7580
String javaParameterName) {

‎spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/misc/DescriptionSnippet.java‎

Lines changed: 4 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@
2424
import java.util.HashMap;
2525
import java.util.Map;
2626

27+
import capital.scalable.restdocs.javadoc.JavadocReader;
2728
import org.springframework.restdocs.operation.Operation;
2829
import org.springframework.restdocs.snippet.TemplatedSnippet;
2930
import org.springframework.web.method.HandlerMethod;
@@ -39,15 +40,10 @@ public DescriptionSnippet() {
3940
@Override
4041
protected Map<String, Object> createModel(Operation operation) {
4142
HandlerMethod handlerMethod = getHandlerMethod(operation);
43+
JavadocReader javadocReader = getJavadocReader(operation);
4244

43-
String methodComment;
44-
if (handlerMethod != null) {
45-
methodComment = getJavadocReader(operation)
46-
.resolveMethodComment(handlerMethod.getBeanType(),
47-
handlerMethod.getMethod().getName());
48-
} else {
49-
methodComment = "";
50-
}
45+
String methodComment = javadocReader.resolveMethodComment(handlerMethod.getBeanType(),
46+
handlerMethod.getMethod().getName());
5147

5248
methodComment = convertFromJavadoc(methodComment, determineForcedLineBreak(operation));
5349

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

Lines changed: 16 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@
1919
import static capital.scalable.restdocs.OperationAttributeHelper.getDefaultSnippets;
2020
import static capital.scalable.restdocs.OperationAttributeHelper.getDocumentationContext;
2121
import static capital.scalable.restdocs.OperationAttributeHelper.getHandlerMethod;
22+
import static capital.scalable.restdocs.OperationAttributeHelper.getJavadocReader;
2223
import static org.apache.commons.lang3.StringUtils.join;
2324
import static org.apache.commons.lang3.StringUtils.splitByCharacterTypeCamelCase;
2425
import static org.springframework.util.StringUtils.capitalize;
@@ -30,6 +31,8 @@
3031
import java.util.Map;
3132

3233
import capital.scalable.restdocs.SnippetRegistry;
34+
import capital.scalable.restdocs.javadoc.JavadocReader;
35+
import org.apache.commons.lang3.StringUtils;
3336
import org.springframework.restdocs.operation.Operation;
3437
import org.springframework.restdocs.snippet.RestDocumentationContextPlaceholderResolverFactory;
3538
import org.springframework.restdocs.snippet.Snippet;
@@ -59,13 +62,9 @@ public SectionSnippet(Collection<String> sectionNames, boolean skipEmpty) {
5962
@Override
6063
protected Map<String, Object> createModel(Operation operation) {
6164
HandlerMethod handlerMethod = getHandlerMethod(operation);
62-
final String title;
63-
if (handlerMethod != null) {
64-
title = join(splitByCharacterTypeCamelCase(
65-
capitalize(handlerMethod.getMethod().getName())), ' ');
66-
} else {
67-
title = "";
68-
}
65+
JavadocReader javadocReader = getJavadocReader(operation);
66+
67+
String title = resolveTitle(handlerMethod, javadocReader);
6968

7069
// resolve path
7170
String path = propertyPlaceholderHelper.replacePlaceholders(operation.getName(),
@@ -93,6 +92,16 @@ protected Map<String, Object> createModel(Operation operation) {
9392
return model;
9493
}
9594

95+
private String resolveTitle(HandlerMethod handlerMethod, JavadocReader javadocReader) {
96+
String title = javadocReader.resolveMethodTitle(handlerMethod.getBeanType(),
97+
handlerMethod.getMethod().getName());
98+
if (StringUtils.isBlank(title)) {
99+
title = join(splitByCharacterTypeCamelCase(
100+
capitalize(handlerMethod.getMethod().getName())), ' ');
101+
}
102+
return title;
103+
}
104+
96105
private SectionSupport getSectionSnippet(Operation operation, String snippetName) {
97106
for (Snippet snippet : getDefaultSnippets(operation)) {
98107
if (snippet instanceof SectionSupport) {

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

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,12 @@ public void resolveComments() {
3434
// line breaks are not handled here - pure javadoc
3535
assertThat(comment, equalTo("Very useful method<br>\n with new line"));
3636

37+
comment = javadocReader.resolveMethodTitle(IntegrationType.class, "dummyMethod");
38+
assertThat(comment, equalTo("My Dummy Method"));
39+
40+
comment = javadocReader.resolveMethodTitle(IntegrationType.class, "dummyMethod2");
41+
assertThat(comment, equalTo(""));
42+
3743
comment = javadocReader.resolveMethodParameterComment(IntegrationType.class, "dummyMethod",
3844
"kindaParameter");
3945
assertThat(comment, equalTo("mandatory param"));
@@ -54,8 +60,12 @@ static class IntegrationType {
5460
* with new line
5561
*
5662
* @param kindaParameter mandatory param
63+
* @title My Dummy Method
5764
*/
5865
private void dummyMethod(String kindaParameter) {
5966
}
67+
68+
private void dummyMethod2() {
69+
}
6070
}
6171
}

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

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,20 @@ public void resolveMethodCommentFromClasspath() {
6666
assertThat(comment, equalTo("Simple method comment from classpath"));
6767
}
6868

69+
@Test
70+
public void resolveMethodTitle() {
71+
JavadocReader javadocReader = JavadocReaderImpl.createWith(SOURCE_DIR);
72+
String comment = javadocReader.resolveMethodTitle(SimpleType.class, "simpleMethod");
73+
assertThat(comment, equalTo("Simple method title"));
74+
}
75+
76+
@Test
77+
public void resolveMethodTitleFromClasspath() {
78+
JavadocReader javadocReader = JavadocReaderImpl.createWith(null);
79+
String comment = javadocReader.resolveMethodTitle(SimpleType.class, "simpleMethod");
80+
assertThat(comment, equalTo("Simple method title from classpath"));
81+
}
82+
6983
@Test
7084
public void resolveMethodParameterComment() {
7185
JavadocReader javadocReader = JavadocReaderImpl.createWith(SOURCE_DIR);
@@ -91,6 +105,8 @@ public void jsonFileDoesNotExist() {
91105
assertThat(comment, is(""));
92106
comment = javadocReader.resolveMethodComment(NotExisting.class, "simpleMethod");
93107
assertThat(comment, is(""));
108+
comment = javadocReader.resolveMethodTitle(NotExisting.class, "simpleMethod");
109+
assertThat(comment, is(""));
94110
comment = javadocReader.resolveMethodParameterComment(NotExisting.class, "simpleMethod",
95111
"simpleParameter");
96112
assertThat(comment, is(""));
@@ -105,6 +121,8 @@ public void jsonNotDocumented() {
105121
assertThat(comment, is(""));
106122
comment = javadocReader.resolveMethodComment(SimpleType.class, "simpleMethod2");
107123
assertThat(comment, is(""));
124+
comment = javadocReader.resolveMethodTitle(SimpleType.class, "simpleMethod2");
125+
assertThat(comment, is(""));
108126
comment = javadocReader.resolveMethodParameterComment(SimpleType.class, "simpleMethod",
109127
"simpleParameter2");
110128
assertThat(comment, is(""));

0 commit comments

Comments
 (0)