Page MenuHomePhabricator

comment-brief-parser-use-returns-paragraph-v1.patch

comment-brief-parser-use-returns-paragraph-v1.patch

Index: test/Index/annotate-comments.cpp
===================================================================
--- test/Index/annotate-comments.cpp (revision 160518)
+++ test/Index/annotate-comments.cpp (working copy)
@@ -213,6 +213,14 @@
/// \returns ddd IS_DOXYGEN_END
void isdoxy48(int);
+/// \brief IS_DOXYGEN_START Aaa
+/// \returns bbb IS_DOXYGEN_END
+void isdoxy49(void);
+
+/// \param ccc IS_DOXYGEN_START
+/// \returns ddd IS_DOXYGEN_END
+void isdoxy50(int);
+
#endif
// RUN: rm -rf %t
@@ -279,4 +287,6 @@
// CHECK: annotate-comments.cpp:195:6: FunctionDecl=isdoxy45:{{.*}} BriefComment=[Ddd eee. Fff.]
// CHECK: annotate-comments.cpp:205:6: FunctionDecl=isdoxy46:{{.*}} BriefComment=[Ddd eee. Fff.]
// CHECK: annotate-comments.cpp:214:6: FunctionDecl=isdoxy48:{{.*}} BriefComment=[IS_DOXYGEN_START Aaa bbb]
+// CHECK: annotate-comments.cpp:218:6: FunctionDecl=isdoxy49:{{.*}} BriefComment=[IS_DOXYGEN_START Aaa]
+// CHECK: annotate-comments.cpp:222:6: FunctionDecl=isdoxy50:{{.*}} BriefComment=[ddd IS_DOXYGEN_END]
Index: include/clang/AST/CommentBriefParser.h
===================================================================
--- include/clang/AST/CommentBriefParser.h (revision 160518)
+++ include/clang/AST/CommentBriefParser.h (working copy)
@@ -20,8 +20,13 @@
namespace clang {
namespace comments {
-/// A very simple comment parser that extracts just the brief description or
-/// first paragraph.
+/// A very simple comment parser that extracts "a brief description".
+///
+/// Due to a variety of comment styles, it considers the following as "a brief
+/// description", in order of priority:
+/// \li a \\brief or \\short command,
+/// \li the first paragraph,
+/// \li a \\result or \\return or \\returns paragraph.
class BriefParser {
Lexer &L;
Index: lib/AST/CommentBriefParser.cpp
===================================================================
--- lib/AST/CommentBriefParser.cpp (revision 160518)
+++ lib/AST/CommentBriefParser.cpp (working copy)
@@ -53,14 +53,18 @@
} // unnamed namespace
std::string BriefParser::Parse() {
- std::string Paragraph;
+ std::string FirstParagraphOrBrief;
+ std::string ReturnsParagraph;
bool InFirstParagraph = true;
bool InBrief = false;
+ bool InReturns = false;
while (Tok.isNot(tok::eof)) {
if (Tok.is(tok::text)) {
if (InFirstParagraph || InBrief)
- Paragraph += Tok.getText();
+ FirstParagraphOrBrief += Tok.getText();
+ else if (InReturns)
+ ReturnsParagraph += Tok.getText();
ConsumeToken();
continue;
}
@@ -68,11 +72,14 @@
if (Tok.is(tok::command)) {
StringRef Name = Tok.getCommandName();
if (Name == "brief" || Name == "short") {
- Paragraph.clear();
+ FirstParagraphOrBrief.clear();
InBrief = true;
ConsumeToken();
continue;
}
+ if (Name == "result" || Name == "return" || Name == "returns") {
+ InReturns = true;
+ }
// Block commands implicitly start a new paragraph.
if (isBlockCommand(Name)) {
// We found an implicit paragraph end.
@@ -84,13 +91,16 @@
if (Tok.is(tok::newline)) {
if (InFirstParagraph || InBrief)
- Paragraph += ' ';
+ FirstParagraphOrBrief += ' ';
+ else if (InReturns)
+ ReturnsParagraph += ' ';
ConsumeToken();
if (Tok.is(tok::newline)) {
ConsumeToken();
// We found a paragraph end.
InFirstParagraph = false;
+ InReturns = false;
if (InBrief)
break;
}
@@ -101,8 +111,12 @@
ConsumeToken();
}
- cleanupBrief(Paragraph);
- return Paragraph;
+ cleanupBrief(FirstParagraphOrBrief);
+ if (!FirstParagraphOrBrief.empty())
+ return FirstParagraphOrBrief;
+
+ cleanupBrief(ReturnsParagraph);
+ return ReturnsParagraph;
}
BriefParser::BriefParser(Lexer &L) : L(L)

Event Timeline