[clang-doc] Clean up Markdown output

Make the output for the MDGenerator cleaner and more readable.

Differential Revision: https://reviews.llvm.org/D52754

llvm-svn: 343818

6 files changed, 53 insertions, 29 deletions

diff --git a/clang-tools-extra/clang-doc/MDGenerator.cpp b/clang-tools-extra/clang-doc/MDGenerator.cpp
index 2f523e43989..5deb510e638 100644
--- a/clang-tools-extra/clang-doc/MDGenerator.cpp
+++ b/clang-tools-extra/clang-doc/MDGenerator.cpp
@@ -74,18 +74,18 @@ std::string genReferenceList(const llvm::SmallVectorImpl<Reference> &Refs) {
   return Stream.str();
 }
 
-void writeLine(const Twine &Text, raw_ostream &OS) { OS << Text << "\n"; }
+void writeLine(const Twine &Text, raw_ostream &OS) { OS << Text << "\n\n"; }
 
-void writeNewLine(raw_ostream &OS) { OS << "\n"; }
+void writeNewLine(raw_ostream &OS) { OS << "\n\n"; }
 
 void writeHeader(const Twine &Text, unsigned int Num, raw_ostream &OS) {
-  OS << std::string(Num, '#') + " " + Text << "\n";
+  OS << std::string(Num, '#') + " " + Text << "\n\n";
 }
 
 void writeFileDefinition(const Location &L, raw_ostream &OS) {
   OS << genItalic("Defined at line " + std::to_string(L.LineNumber) + " of " +
                   L.Filename)
-     << "\n";
+     << "\n\n";
 }
 
 void writeDescription(const CommentInfo &I, raw_ostream &OS) {
@@ -104,10 +104,10 @@ void writeDescription(const CommentInfo &I, raw_ostream &OS) {
     OS << genEmphasis(I.Name) << " " << I.Text;
   } else if (I.Kind == "ParamCommandComment") {
     std::string Direction = I.Explicit ? (" " + I.Direction).str() : "";
-    OS << genEmphasis(I.ParamName) << I.Text << Direction << "\n";
+    OS << genEmphasis(I.ParamName) << I.Text << Direction << "\n\n";
   } else if (I.Kind == "TParamCommandComment") {
     std::string Direction = I.Explicit ? (" " + I.Direction).str() : "";
-    OS << genEmphasis(I.ParamName) << I.Text << Direction << "\n";
+    OS << genEmphasis(I.ParamName) << I.Text << Direction << "\n\n";
   } else if (I.Kind == "VerbatimBlockComment") {
     for (const auto &Child : I.Children)
       writeDescription(*Child, OS);
@@ -132,7 +132,7 @@ void writeDescription(const CommentInfo &I, raw_ostream &OS) {
   } else if (I.Kind == "TextComment") {
     OS << I.Text;
   } else {
-    OS << "Unknown comment kind: " << I.Kind << ".\n";
+    OS << "Unknown comment kind: " << I.Kind << ".\n\n";
   }
 }
 
@@ -166,11 +166,16 @@ void genMarkdown(const FunctionInfo &I, llvm::raw_ostream &OS) {
     Stream << N.Type.Name + " " + N.Name;
     First = false;
   }
+  writeHeader(I.Name, 3, OS);
   std::string Access = getAccess(I.Access);
   if (Access != "")
-    writeHeader(genItalic(Access) + " " + I.ReturnType.Type.Name + " " + I.Name + "(" + Stream.str() + ")", 3, OS);
-  else 
-    writeHeader(I.ReturnType.Type.Name + " " + I.Name + "(" + Stream.str() + ")", 3, OS);
+    writeLine(genItalic(Access + " " + I.ReturnType.Type.Name + " " + I.Name +
+                        "(" + Stream.str() + ")"),
+              OS);
+  else
+    writeLine(genItalic(I.ReturnType.Type.Name + " " + I.Name + "(" +
+                        Stream.str() + ")"),
+              OS);
   if (I.DefLoc)
     writeFileDefinition(I.DefLoc.getValue(), OS);
 
diff --git a/clang-tools-extra/test/clang-doc/md-comment.cpp b/clang-tools-extra/test/clang-doc/md-comment.cpp
index ae14eaac239..8e8f97a97d5 100644
--- a/clang-tools-extra/test/clang-doc/md-comment.cpp
+++ b/clang-tools-extra/test/clang-doc/md-comment.cpp
@@ -33,7 +33,8 @@ void F(int I, int J) {}
 // RUN: cat %t/docs/./GlobalNamespace.md | FileCheck %s --check-prefix CHECK-0
 // CHECK-0: # Global Namespace
 // CHECK-0: ## Functions
-// CHECK-0: ### void F(int I, int J)
+// CHECK-0: ### F
+// CHECK-0: *void F(int I, int J)*
 // CHECK-0: *Defined at line 28 of test*
 // CHECK-0: **brief** Brief description.
 // CHECK-0:  Extended description that continues onto the next line.
diff --git a/clang-tools-extra/test/clang-doc/md-linkage.cpp b/clang-tools-extra/test/clang-doc/md-linkage.cpp
index 942ff35339f..ffc6a3d78bd 100644
--- a/clang-tools-extra/test/clang-doc/md-linkage.cpp
+++ b/clang-tools-extra/test/clang-doc/md-linkage.cpp
@@ -104,23 +104,31 @@ inline void anonInlineFunction();
 // CHECK-0: int publicField
 // CHECK-0: protected int protectedField
 // CHECK-0: ## Functions
-// CHECK-0: ### void publicMethod()
-// CHECK-0: ### void protectedMethod()
+// CHECK-0: ### publicMethod
+// CHECK-0: *void publicMethod()*
+// CHECK-0: ### protectedMethod
+// CHECK-0: *void protectedMethod()*
 
 // RUN: cat %t/docs/./named.md | FileCheck %s --check-prefix CHECK-1
 // CHECK-1: # namespace named
 // CHECK-1: ## Functions
-// CHECK-1: ### void namedFunction()
-// CHECK-1: ### void namedInlineFunction()
+// CHECK-1: ### namedFunction
+// CHECK-1: *void namedFunction()*
+// CHECK-1: ### namedInlineFunction
+// CHECK-1: *void namedInlineFunction()*
 
 // RUN: cat %t/docs/./GlobalNamespace.md | FileCheck %s --check-prefix CHECK-2
 // CHECK-2: # Global Namespace
 // CHECK-2: ## Functions
-// CHECK-2: ### void function(int x)
-// CHECK-2: ### int inlinedFunction(int x)
-// CHECK-2: ### int functionWithInnerClass(int x)
+// CHECK-2: ### function
+// CHECK-2: *void function(int x)*
+// CHECK-2: ### inlinedFunction
+// CHECK-2: *int inlinedFunction(int x)*
+// CHECK-2: ### functionWithInnerClass
+// CHECK-2: *int functionWithInnerClass(int x)*
 // CHECK-2: *Defined at line 14 of test*
-// CHECK-2: ### int inlinedFunctionWithInnerClass(int x)
+// CHECK-2: ### inlinedFunctionWithInnerClass
+// CHECK-2: *int inlinedFunctionWithInnerClass(int x)*
 // CHECK-2: *Defined at line 23 of test*
 
 // RUN: cat %t/docs/named/NamedClass.md | FileCheck %s --check-prefix CHECK-3
@@ -130,5 +138,7 @@ inline void anonInlineFunction();
 // CHECK-3: int namedPublicField
 // CHECK-3: protected int namedProtectedField
 // CHECK-3: ## Functions
-// CHECK-3: ### void namedPublicMethod()
-// CHECK-3: ### void namedProtectedMethod()
+// CHECK-3: ### namedPublicMethod
+// CHECK-3: *void namedPublicMethod()*
+// CHECK-3: ### namedProtectedMethod
+// CHECK-3: *void namedProtectedMethod()*
diff --git a/clang-tools-extra/test/clang-doc/md-module.cpp b/clang-tools-extra/test/clang-doc/md-module.cpp
index 936f621bca9..33de5aef5dc 100644
--- a/clang-tools-extra/test/clang-doc/md-module.cpp
+++ b/clang-tools-extra/test/clang-doc/md-module.cpp
@@ -20,5 +20,7 @@ export double exportedModuleFunction(double y, int z); // ExternalLinkage
 // RUN: cat %t/docs/./GlobalNamespace.md | FileCheck %s --check-prefix CHECK-0
 // CHECK-0: # Global Namespace
 // CHECK-0: ## Functions
-// CHECK-0: ### int moduleFunction(int x)
-// CHECK-0: ### double exportedModuleFunction(double y, int z)
+// CHECK-0: ### moduleFunction
+// CHECK-0: *int moduleFunction(int x)*
+// CHECK-0: ### exportedModuleFunction
+// CHECK-0: *double exportedModuleFunction(double y, int z)*
diff --git a/clang-tools-extra/test/clang-doc/md-namespace.cpp b/clang-tools-extra/test/clang-doc/md-namespace.cpp
index 6db3fffd221..e2fddf4eb2e 100644
--- a/clang-tools-extra/test/clang-doc/md-namespace.cpp
+++ b/clang-tools-extra/test/clang-doc/md-namespace.cpp
@@ -31,13 +31,15 @@ E func(int i) { return X; }
 // RUN: cat %t/docs/./A.md | FileCheck %s --check-prefix CHECK-0
 // CHECK-0: # namespace A
 // CHECK-0: ## Functions
-// CHECK-0: ### void f()
+// CHECK-0: ### f
+// CHECK-0: *void f()*
 // CHECK-0: *Defined at line 17 of test*
 
 // RUN: cat %t/docs/A/B.md | FileCheck %s --check-prefix CHECK-1
 // CHECK-1: # namespace B
 // CHECK-1: ## Functions
-// CHECK-1: ### enum A::B::E func(int i)
+// CHECK-1: ### func
+// CHECK-1: *enum A::B::E func(int i)*
 // CHECK-1: *Defined at line 23 of test*
 // CHECK-1: ## Enums
 // CHECK-1: | enum E |
diff --git a/clang-tools-extra/test/clang-doc/md-record.cpp b/clang-tools-extra/test/clang-doc/md-record.cpp
index 0d3e0ccc268..93fbe1607ef 100644
--- a/clang-tools-extra/test/clang-doc/md-record.cpp
+++ b/clang-tools-extra/test/clang-doc/md-record.cpp
@@ -56,7 +56,8 @@ class G;
 // RUN: cat %t/docs/./GlobalNamespace.md | FileCheck %s --check-prefix CHECK-2
 // CHECK-2: # Global Namespace
 // CHECK-2: ## Functions
-// CHECK-2: ### void H()
+// CHECK-2: ### H
+// CHECK-2: *void H()*
 // CHECK-2: *Defined at line 11 of test*
 // CHECK-2: ## Enums
 // CHECK-2: | enum B |
@@ -74,11 +75,14 @@ class G;
 // CHECK-3: # class E
 // CHECK-3: *Defined at line 25 of test*
 // CHECK-3: ## Functions
-// CHECK-3: ### void E()
+// CHECK-3: ### E
+// CHECK-3: *void E()*
 // CHECK-3: *Defined at line 27 of test*
-// CHECK-3: ### void ~E()
+// CHECK-3: ### ~E
+// CHECK-3: *void ~E()*
 // CHECK-3: *Defined at line 28 of test*
-// CHECK-3: ### void ProtectedMethod()
+// CHECK-3: ### ProtectedMethod
+// CHECK-3: *void ProtectedMethod()*
 // CHECK-3: *Defined at line 34 of test*
 
 // RUN: cat %t/docs/./C.md | FileCheck %s --check-prefix CHECK-4