[MLIR][Doc] Also print `summary`s for passes on a newline

[rikhuijzer]

Summary

This patch is improves upon https://reviews.llvm.org/D152621. There, I pointed out some issues with D152621, which I'll repeat here.

Passes use a different logic for generating the documentation; which I didn't update to be in-line with this change.

Fixed by defining and using mlir::tblgen::emitSummary. This is now used in OpDocGen.cpp and PassDocGen.cpp.

Note that the passes documentation currently prints the summary behind the pass argument. For example:

#### -arm-neon-2d-to-intr: Convert Arm NEON structured ops to intrinsics

at https://mlir.llvm.org/docs/Passes/#-promote-buffers-to-stack-promotes-heap-based-allocations-to-automatically-managed-stack-based-allocations.

This currently differs from how the summary is printed for Ops. For example:

#### amdgpu.lds_barrier (::mlir::amdgpu::LDSBarrierOp) ¶

**Summary:** _Barrier that includes a wait for LDS memory operations._

at https://mlir.llvm.org/docs/Dialects/AMDGPU/#amdgpulds_barrier-mliramdgpuldsbarrierop.

The changes in this patch ensure that:

1. The summary is always printed on a new line.
2. The summary is always printed in italic.
3. The summary always starts with a capital letter.

I've dropped the **Summary:**, which was introduced in D152621, because only italicization should be already clear enough.

amx.tdpbssd shows Summary: __ meaning that apparently hasSummary does not guarantee a non-empty summary.

This is fixed by double-checking !summary.empty(), because the following code

cpp
void mlir::tblgen::emitSummary(StringRef summary, raw_ostream &os) {
  if (!summary.empty()) {
    char first = std::toupper(summary.front());
    llvm::StringRef rest = summary.drop_front();
    os << "\n_" << first << rest << "_\n\n";
  } else {
    os << "\n_" << "foo" << "_\n\n";
  }
}

generates the following Markdown:

### `amx.tdpbssd` (::mlir::amx::x86_amx_tdpbssd)

_foo_

in tools/mlir/docs/Dialects/AMX.md.

Summary fields containing * cancel the italicization, so the * should probably be escaped to solve this. EDIT: Nope. This is because mlir-www runs Hugo 0.80 whereas 0.111 correctly parses _Raw Buffer Floating-point Atomic Add (MI-* only)_ as an italicized string.

This will be fixed by https://github.com/llvm/mlir-www/pull/152.

mlir/docs/DefiningDialects/Operations.md

 }];
 ```
 
 `description` should be written in Markdown syntax.
 
 Placing the documentation at the beginning is recommended since it helps in
 understanding the operation.
 
-> *   Place documentation at the beginning of the operation definition
-> *   The summary should be short and concise. It should be a one-liner without
->     trailing punctuation. Put expanded explanation in description.
+> *   Place documentation at the beginning of the operation definition.
+> *   The summary should be short and concise. It should be a one-liner
+>     starting with a capital letter and without trailing punctuation.
+>     Put expanded explanation in the description.
 
 ### Operation arguments
 
 There are two kinds of arguments: operands and attributes. Operands are runtime
 values produced by other ops; while attributes are compile-time known constant
 values, including two categories:
 
 1.  Natural attributes: these attributes affect the behavior of the operations

mlir/tools/mlir-tblgen/DocGenUtilities.h

 
 namespace llvm {
 class raw_ostream;
 } // namespace llvm
 
 namespace mlir {
 namespace tblgen {
 
+// Emit the summary. To avoid confusion, the summary is styled differently from
+// the description.
+void emitSummary(llvm::StringRef summary, llvm::raw_ostream &os);
+
 // Emit the description by aligning the text to the left per line (e.g.
 // removing the minimum indentation across the block).
 //
 // This expects that the description in the tablegen file is already formatted
 // in a way the user wanted but has some additional indenting due to being
 // nested.
 void emitDescription(llvm::StringRef description, llvm::raw_ostream &os);
 
 // Emit the description as a C++ comment while realigning it.
 void emitDescriptionComment(llvm::StringRef description, llvm::raw_ostream &os,
                             llvm::StringRef prefix = "");
 
 } // namespace tblgen
 } // namespace mlir
 
 #endif // MLIR_TOOLS_MLIRTBLGEN_DOCGENUTILITIES_H_

mlir/tools/mlir-tblgen/OpDocGen.cpp

llvm::cl::opt<std::string> stripPrefix(
     llvm::cl::desc("Strip prefix of the fully qualified names"),
     llvm::cl::init("::mlir::"), llvm::cl::cat(docCat));
 
 using namespace llvm;
 using namespace mlir;
 using namespace mlir::tblgen;
 using mlir::tblgen::Operator;
 
+void mlir::tblgen::emitSummary(StringRef summary, raw_ostream &os) {
+  if (!summary.empty()) {
+    char first = std::toupper(summary.front());
+    llvm::StringRef rest = summary.drop_front();
+    os << "\n_" << first << rest << "_\n\n";
+  }
+}
+
 // Emit the description by aligning the text to the left per line (e.g.,
 // removing the minimum indentation across the block).
 //
 // This expects that the description in the tablegen file is already formatted
 // in a way the user wanted but has some additional indenting due to being
 // nested in the op definition.
 void mlir::tblgen::emitDescription(StringRef description, raw_ostream &os) {
   raw_indented_ostream ros(os);

 static void emitOpDoc(const Operator &op, raw_ostream &os) {
   std::string classNameStr = op.getQualCppClassName();
   StringRef className = classNameStr;
   (void)className.consume_front(stripPrefix);
   os << llvm::formatv("### `{0}` ({1})\n", op.getOperationName(), className);
 
   // Emit the summary, syntax, and description if present.
   if (op.hasSummary())
-    os << "\n**Summary:** _" << op.getSummary() << "_\n\n";
+    emitSummary(op.getSummary(), os);
   if (op.hasAssemblyFormat())
     emitAssemblyFormat(op.getOperationName(), op.getAssemblyFormat().trim(),
                        os);
   if (op.hasDescription())
     mlir::tblgen::emitDescription(op.getDescription(), os);
 
   emitOpTraitsDoc(op, os);
 

mlir/tools/mlir-tblgen/PassDocGen.cpp

 #include "llvm/Support/FormatVariadic.h"
 #include "llvm/TableGen/Record.h"
 
 using namespace mlir;
 using namespace mlir::tblgen;
 
 /// Emit the documentation for the given pass.
 static void emitDoc(const Pass &pass, raw_ostream &os) {
-  os << llvm::formatv("### `-{0}`: {1}\n", pass.getArgument(),
-                      pass.getSummary());
+  os << llvm::formatv("### `-{0}`\n", pass.getArgument());
+  emitSummary(pass.getSummary(), os);
   emitDescription(pass.getDescription(), os);
 
   // Handle the options of the pass.
   ArrayRef<PassOption> options = pass.getOptions();
   if (!options.empty()) {
     os << "\n#### Options\n```\n";
     size_t longestOption = 0;
     for (const PassOption &option : options)