CommentBriefParser: use \returns if we can't find the \brief or just a plain

paragraph.

llvm-svn: 160550

clang/include/clang/AST/CommentBriefParser.h

@@ -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;
 

clang/lib/AST/CommentBriefParser.cpp

@@ -53,14 +53,18 @@ bool isBlockCommand(StringRef Name) {
 } // 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,15 @@ std::string BriefParser::Parse() {
     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;
+        ReturnsParagraph += "Returns ";
+      }
       // Block commands implicitly start a new paragraph.
       if (isBlockCommand(Name)) {
         // We found an implicit paragraph end.
@@ -84,13 +92,16 @@ std::string BriefParser::Parse() {
 
     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 +112,12 @@ std::string BriefParser::Parse() {
     ConsumeToken();
   }
 
-  cleanupBrief(Paragraph);
-  return Paragraph;
+  cleanupBrief(FirstParagraphOrBrief);
+  if (!FirstParagraphOrBrief.empty())
+    return FirstParagraphOrBrief;
+
+  cleanupBrief(ReturnsParagraph);
+  return ReturnsParagraph;
 }
 
 BriefParser::BriefParser(Lexer &L) : L(L)

clang/test/Index/annotate-comments.cpp

@@ -213,6 +213,14 @@ void notdoxy47(void);
 /// \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 @@ void isdoxy48(int);
 // 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=[Returns ddd IS_DOXYGEN_END]