[clang-doc] Clean up Markdown output

[juliehockett]

Summary

Make the output for the MDGenerator cleaner and more readable.

clang-tools-extra/clang-doc/MDGenerator.cpp

for (const auto &R : Refs) {
     if (!First)
       Stream << ", ";
     Stream << R.Name;
     First = false;
   }
   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) {
   if (I.Kind == "FullComment") {
     for (const auto &Child : I.Children)
       writeDescription(*Child, OS);
   } else if (I.Kind == "ParagraphComment") {
     for (const auto &Child : I.Children)
       writeDescription(*Child, OS);
     writeNewLine(OS);
   } else if (I.Kind == "BlockCommandComment") {
     OS << genEmphasis(I.Name);
     for (const auto &Child : I.Children)
       writeDescription(*Child, OS);
   } else if (I.Kind == "InlineCommandComment") {
     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);
   } else if (I.Kind == "VerbatimBlockLineComment") {
     OS << I.Text;
     writeNewLine(OS);
   } else if (I.Kind == "VerbatimLineComment") {
     OS << I.Text;
     writeNewLine(OS);
   } else if (I.Kind == "HTMLStartTagComment") {
     if (I.AttrKeys.size() != I.AttrValues.size())
       return;
     std::string Buffer;
     llvm::raw_string_ostream Attrs(Buffer);
     for (unsigned Idx = 0; Idx < I.AttrKeys.size(); ++Idx)
       Attrs << " \"" << I.AttrKeys[Idx] << "=" << I.AttrValues[Idx] << "\"";
 
     std::string CloseTag = I.SelfClosing ? "/>" : ">";
     writeLine("<" + I.Name + Attrs.str() + CloseTag, OS);
   } else if (I.Kind == "HTMLEndTagComment") {
     writeLine("</" + I.Name + ">", 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";
   }
 }
 
 void genMarkdown(const EnumInfo &I, llvm::raw_ostream &OS) {
   if (I.Scoped)
     writeLine("| enum class " + I.Name + " |", OS);
   else
     writeLine("| enum " + I.Name + " |", OS);
void genMarkdown(const FunctionInfo &I, llvm::raw_ostream &OS) {
   llvm::raw_string_ostream Stream(Buffer);
   bool First = true;
   for (const auto &N : I.Params) {
     if (!First)
       Stream << ", ";
     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);
 
   for (const auto &C : I.Description)
     writeDescription(C, OS);
 }
 
 void genMarkdown(const NamespaceInfo &I, llvm::raw_ostream &OS) {

clang-tools-extra/test/clang-doc/md-comment.cpp

 void F(int I, int J) {}
 
 // RUN: clang-doc --format=md --doxygen --public --extra-arg=-fmodules-ts -p %t %t/test.cpp -output=%t/docs
 
 
 // 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.
 // CHECK-0: <ul "class=test">
 // CHECK-0: <li>
 // CHECK-0:  Testing.</ul>
 // CHECK-0:  The description continues.
 // CHECK-0:  --
 // CHECK-0: **I** [out]
 // CHECK-0: **J**
 // CHECK-0: **return** void
 // CHECK-0:  Bonus comment on definition

clang-tools-extra/test/clang-doc/md-linkage.cpp

 
 // RUN: cat %t/docs/./Class.md | FileCheck %s --check-prefix CHECK-0
 // CHECK-0: # class Class
 // CHECK-0: *Defined at line 32 of test*
 // CHECK-0: ## Members
 // 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
 // CHECK-3: # class NamedClass
 // CHECK-3: *Defined at line 47 of test*
 // CHECK-3: ## Members
 // 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()*

clang-tools-extra/test/clang-doc/md-module.cpp

 export double exportedModuleFunction(double y, int z); // ExternalLinkage
 
 // RUN: clang-doc --format=md --doxygen --public --extra-arg=-fmodules-ts -p %t %t/test.cpp -output=%t/docs
 
 
 // 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)*

clang-tools-extra/test/clang-doc/md-namespace.cpp

 }  // namespace A
 
 // RUN: clang-doc --format=md --doxygen --public --extra-arg=-fmodules-ts -p %t %t/test.cpp -output=%t/docs
 
 
 // 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 |
 // CHECK-1: --
 // CHECK-1: | X |
 // CHECK-1: *Defined at line 21 of test*

clang-tools-extra/test/clang-doc/md-record.cpp

 
 // RUN: cat %t/docs/./D.md | FileCheck %s --check-prefix CHECK-1
 // CHECK-1: # class D
 // CHECK-1: *Defined at line 23 of test*
 
 // 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 |
 // CHECK-2: --
 // CHECK-2: | X |
 // CHECK-2: | Y |
 // CHECK-2: *Defined at line 17 of test*
 // CHECK-2: | enum class Bc |
 // CHECK-2: --
 // CHECK-2: | A |
 // CHECK-2: | B |
 // CHECK-2: *Defined at line 19 of test*
 
 // RUN: cat %t/docs/./E.md | FileCheck %s --check-prefix CHECK-3
 // 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
 // CHECK-4: # struct C
 // CHECK-4: *Defined at line 21 of test*
 // CHECK-4: ## Members
 // CHECK-4: int i