Skip to content

fix: extract first line as plain-text title from Javadoc comments #20

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
shalousun merged 1 commit into from
Jul 11, 2026
Merged

fix: extract first line as plain-text title from Javadoc comments #20

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion src/main/java/io/github/smartdoc/template/IJavadocDocTemplate.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -99,7 +99,7 @@ default T convertToJavadocJavaMethod(ApiConfig apiConfig, JavaMethod method, Map

javadocJavaMethod.setMethodDefinition(methodDefine);
javadocJavaMethod.setEscapeMethodDefinition(scapeMethod);
javadocJavaMethod.setDesc(DocUtil.getEscapeAndCleanComment(method.getComment()));
javadocJavaMethod.setDesc(DocUtil.getCommentFirstLine(method.getComment()));
// set detail
String apiNoteValue = DocUtil.getNormalTagComments(method, DocTags.API_NOTE, cls.getName());
if (StringUtil.isEmpty(apiNoteValue)) {
Expand Down
8 changes: 4 additions & 4 deletions src/main/java/io/github/smartdoc/template/IRestDocTemplate.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -283,10 +283,10 @@ default void handleApiDoc(JavaClass cls, List<ApiDoc> apiDocList, List<ApiMethod
String name = DocUtil.generateId(apiDoc.getName());
apiDoc.setAlias(name);
}
String desc = DocUtil.getEscapeAndCleanComment(cls.getComment());
String desc = DocUtil.getCommentFirstLine(cls.getComment());
String detail = JavaClassUtil.getClassTagsValue(cls, DocTags.API_NOTE, Boolean.TRUE);
if (StringUtil.isEmpty(detail)) {
detail = desc;
detail = cls.getComment();
}
apiDoc.setDesc(StringUtil.isEmpty(desc) ? controllerName : desc);
apiDoc.setDetail(detail);
Expand Down Expand Up @@ -823,7 +823,7 @@ else if (Objects.nonNull(classMediaType)) {
methodOrder++;
apiMethodDoc.setOrder(methodOrder);
apiMethodDoc.setName(method.getName());
String common = method.getComment();
String common = DocUtil.getCommentFirstLine(method.getComment());
if (StringUtil.isEmpty(common)) {
common = JavaClassUtil.getSameSignatureMethodCommonFromInterface(cls, method);
}
Expand Down Expand Up @@ -1758,7 +1758,7 @@ default DocJavaMethod convertToDocJavaMethod(ApiConfig apiConfig, ProjectDocConf
docJavaMethod.setAuthor(classAuthor);
}

String comment = DocUtil.getEscapeAndCleanComment(method.getComment());
String comment = DocUtil.getCommentFirstLine(method.getComment());
docJavaMethod.setDesc(comment);
String version = DocUtil.getNormalTagComments(method, DocTags.SINCE, cls.getName());
docJavaMethod.setVersion(version);
Expand Down
2 changes: 1 addition & 1 deletion src/main/java/io/github/smartdoc/template/IWebSocketTemplate.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -187,7 +187,7 @@ default WebSocketDoc buildEntryPointWebSocketDoc(final JavaClass javaClass, Proj
webSocketDoc.setName(javaClass.getName());
webSocketDoc.setUri(replaceHttpPrefixToWebSocketPrefix(apiConfig.getServerUrl()) + serverEndpoint.getUrl());
webSocketDoc.setPackageName(javaClass.getPackage().getName());
webSocketDoc.setDesc(DocUtil.getEscapeAndCleanComment(javaClass.getComment()));
webSocketDoc.setDesc(DocUtil.getCommentFirstLine(javaClass.getComment()));
webSocketDoc.setAuthor(JavaClassUtil.getClassTagsValue(javaClass, DocTags.AUTHOR, Boolean.TRUE));
webSocketDoc.setOrder(order);
boolean isDeprecated = Objects.nonNull(javaClass.getTagByName(DocTags.DEPRECATED)) || javaClass.getAnnotations()
Expand Down
2 changes: 1 addition & 1 deletion src/main/java/io/github/smartdoc/template/JavadocDocBuildTemplate.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -181,7 +181,7 @@ private void handleJavaApiDoc(JavaClass cls, List<JavadocApiDoc> apiDocList, Lis
String name = DocUtil.generateId(apiDoc.getName());
apiDoc.setAlias(name);
}
apiDoc.setDesc(DocUtil.getEscapeAndCleanComment(comment));
apiDoc.setDesc(DocUtil.getCommentFirstLine(comment));
apiDoc.setList(apiMethodDocs);

List<DocletTag> docletTags = cls.getTags();
Expand Down
2 changes: 1 addition & 1 deletion src/main/java/io/github/smartdoc/template/RpcDocBuildTemplate.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -204,7 +204,7 @@ private void handleJavaApiDoc(JavaClass cls, List<RpcApiDoc> apiDocList, List<Rp
String name = DocUtil.generateId(apiDoc.getName());
apiDoc.setAlias(name);
}
apiDoc.setDesc(DocUtil.getEscapeAndCleanComment(comment));
apiDoc.setDesc(DocUtil.getCommentFirstLine(comment));
apiDoc.setList(apiMethodDocs);

List<JavaAnnotation> annotations = cls.getAnnotations();
Expand Down
25 changes: 25 additions & 0 deletions src/main/java/io/github/smartdoc/utils/DocUtil.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1001,6 +1001,31 @@ public static String getEscapeAndCleanComment(String comment) {
return comment;
}

/**
* Gets the first line of a Javadoc comment as plain text (HTML tags stripped), for
* use as a title/heading. Javadoc convention: the first line is the summary/title,
* and subsequent lines provide the detailed description.
* @param comment the full Javadoc comment (may contain HTML)
* @return the first non-empty line with HTML tags removed, or empty string if
* null/empty
*/
public static String getCommentFirstLine(String comment) {
if (StringUtil.isEmpty(comment)) {
return "";
}
String trimmed = comment.trim();
int newlineIndex = trimmed.indexOf('\n');
String firstLine;
if (newlineIndex > 0) {
firstLine = trimmed.substring(0, newlineIndex).trim();
}
else {
firstLine = trimmed;
}
// Strip HTML tags to produce pure text title
return firstLine.replaceAll("<[^>]*>", "").trim();
}

/**
* Get the url from 'value' or 'path' attribute
* @param classLoader classLoader
Expand Down
2 changes: 2 additions & 0 deletions src/main/resources/template/AllInOne.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -144,7 +144,9 @@
<%}%>
<div class="paragraph" data-content-type="${doc.contentType}" id="${doc.methodId}-content-type"><p><strong>Content-Type:&nbsp;</strong>${doc.contentType}
</p></div>
<%if(isNotEmpty(doc.detail)){%>
<div class="paragraph"><p><strong>Description:&nbsp;</strong>${htmlEscape(doc.detail)}</p></div>
<%}%>
<%if(isNotEmpty(doc.requestHeaders)&&displayRequestParams){%>
<div class="paragraph"><p><strong>Request-headers:</strong></p></div>
<table class="tableblock frame-all grid-all spread">
Expand Down
2 changes: 2 additions & 0 deletions src/main/resources/template/AllInOne.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,9 @@ for(doc in api.list){

**Content-Type:** ${doc.contentType}

<%if(isNotEmpty(doc.detail)){%>
**Description:** ${doc.detail}
<%}%>
<%if(isNotEmpty(doc.requestHeaders)){%>

**Request-headers:**
Expand Down
2 changes: 2 additions & 0 deletions src/main/resources/template/ApiDoc.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,9 @@ for(doc in list){

**Content-Type:** `${doc.contentType}`

<%if(isNotEmpty(doc.detail)){%>
**Description:** ${doc.detail}
<%}%>

<%if(isNotEmpty(doc.requestHeaders)){%>
**Request-headers:**
Expand Down
2 changes: 2 additions & 0 deletions src/main/resources/template/debug-all.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -146,7 +146,9 @@
<%}%>
<div class="paragraph" id="${doc.methodId}-content-type" data-content-type="${doc.contentType}"><p><strong>Content-Type:</strong>&nbsp;${doc.contentType}
</p></div>
<%if(isNotEmpty(doc.detail)){%>
<div class="paragraph"><p><strong>Description:</strong>&nbsp;${htmlEscape(doc.detail)}</p></div>
<%}%>
<%if(isNotEmpty(doc.requestHeaders)&&displayRequestParams){%>
<div class="paragraph"><p><strong>Request-headers:</strong></p></div>
<table class="tableblock frame-all grid-all spread">
Expand Down
2 changes: 2 additions & 0 deletions src/main/resources/template/dubbo/Dubbo.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,9 @@ for(doc in list){
**Author:** ${doc.author}
<%}%>

<%if(isNotEmpty(doc.detail)){%>
**Description:** ${doc.detail}
<%}%>

<%if(isNotEmpty(doc.requestParams)){%>
**Invoke-parameters:**
Expand Down
2 changes: 2 additions & 0 deletions src/main/resources/template/dubbo/DubboAllInOne.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -121,7 +121,9 @@
href="#_${api.order+1}_${doc.order}_${doc.desc}">${api.order+1}.${doc.order}.&nbsp;${htmlEscape(doc.desc)}</a><%}%>
</h3>
<div class="paragraph"><p><strong>Definition:</strong>&nbsp;${doc.escapeMethodDefinition}</p></div>
<%if(isNotEmpty(doc.detail)){%>
<div class="paragraph"><p><strong>Description:</strong>&nbsp;${doc.detail}</p></div>
<%}%>
<%if(isNotEmpty(doc.requestParams)){%>
<div class="paragraph"><p><strong>Invoke-parameters:</strong></p></div>
<table class="tableblock frame-all grid-all spread">
Expand Down
2 changes: 2 additions & 0 deletions src/main/resources/template/dubbo/DubboAllInOne.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,9 @@ ${consumerConfigExample}
**Author:** ${doc.author}
<%}%>

<%if(isNotEmpty(doc.detail)){%>
**Description:** ${doc.detail}
<%}%>

<%if(isNotEmpty(doc.requestParams)){%>
**Invoke-parameters:**
Expand Down
2 changes: 2 additions & 0 deletions src/main/resources/template/grpc/Grpc.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,9 @@
**Author:** ${doc.author}
<%}%>

<%if(isNotEmpty(doc.detail)){%>
**Description:** ${doc.detail}
<%}%>

**MethodType:** ${doc.methodType}

Expand Down
2 changes: 2 additions & 0 deletions src/main/resources/template/grpc/GrpcAllInOne.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,9 @@
href="#_${api.order}_${doc.order}_${htmlEscape(doc.desc)}">${api.order}.${doc.order}.&nbsp;${htmlEscape(doc.desc)}</a><%}%>
</h3>
<div class="paragraph"><p><strong>Definition:</strong>&nbsp;${doc.escapeMethodDefinition}</p></div>
<%if(isNotEmpty(doc.detail)){%>
<div class="paragraph"><p><strong>Description:</strong>&nbsp;${doc.detail}</p>
<%}%>
<div class="paragraph"><p><strong>MethodType:</strong>&nbsp;${doc.methodType}</p></div>
<%if(isNotEmpty(doc.requestParams)){%>
<div class="paragraph"><p><strong>Invoke-parameters:</strong></p></div>
Expand Down
2 changes: 2 additions & 0 deletions src/main/resources/template/grpc/GrpcAllInOne.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,9 @@
**Author:** ${doc.author}
<%}%>

<%if(isNotEmpty(doc.detail)){%>
**Description:** ${doc.detail}
<%}%>

**MethodType:** ${doc.methodType}

Expand Down
2 changes: 2 additions & 0 deletions src/main/resources/template/html/debug.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,9 @@
<%}%>
<div class="paragraph" data-content-type="${doc.contentType}" id="${doc.methodId}-content-type"><p><strong>Content-Type:</strong>&nbsp;${doc.contentType}
</p></div>
<%if(isNotEmpty(doc.detail)){%>
<div class="paragraph"><p><strong>Description:</strong>&nbsp;${lineBreaksToBr(doc.detail)}</p></div>
<%}%>
<%if(isNotEmpty(doc.requestHeaders)){%>
<div class="paragraph"><p><strong>Request-headers:</strong></p></div>
<table class="tableblock frame-all grid-all spread">
Expand Down
2 changes: 2 additions & 0 deletions src/main/resources/template/html/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,9 @@
<div class="paragraph"><p><strong>Author:</strong>&nbsp;${doc.author}</p></div>
<%}%>
<div class="paragraph"><p><strong>Content-Type:</strong>&nbsp;${doc.contentType}</p></div>
<%if(isNotEmpty(doc.detail)){%>
<div class="paragraph"><p><strong>Description:</strong>&nbsp;${lineBreaksToBr(doc.detail)}</p></div>
<%}%>
<%if(isNotEmpty(doc.requestHeaders)){%>
<div class="paragraph"><p><strong>Request-headers:</strong></p></div>
<table class="tableblock frame-all grid-all spread">
Expand Down
2 changes: 2 additions & 0 deletions src/main/resources/template/javadoc/Javadoc.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,9 @@ for(doc in list){
**Author:** ${doc.author}
<%}%>

<%if(isNotEmpty(doc.detail)){%>
**Description:** ${doc.detail}
<%}%>

<%if(isNotEmpty(doc.requestParams)){%>
**Invoke-parameters:**
Expand Down
2 changes: 2 additions & 0 deletions src/main/resources/template/javadoc/JavadocAllInOne.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,7 +119,9 @@
href="#_${api.order+1}_${doc.order}_${doc.desc}">${api.order+1}.${doc.order}.&nbsp;${htmlEscape(doc.desc)}</a><%}%>
</h3>
<div class="paragraph"><p><strong>Definition:</strong>&nbsp;${doc.escapeMethodDefinition}</p></div>
<%if(isNotEmpty(doc.detail)){%>
<div class="paragraph"><p><strong>Description:</strong>&nbsp;${doc.detail}</p></div>
<%}%>
<%if(isNotEmpty(doc.requestParams)){%>
<div class="paragraph"><p><strong>Invoke-parameters:</strong></p></div>
<table class="tableblock frame-all grid-all spread">
Expand Down
2 changes: 2 additions & 0 deletions src/main/resources/template/javadoc/JavadocAllInOne.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,9 @@
**Author:** ${doc.author}
<%}%>

<%if(isNotEmpty(doc.detail)){%>
**Description:** ${doc.detail}
<%}%>

<%if(isNotEmpty(doc.requestParams)){%>
**Invoke-parameters:**
Expand Down
Loading