[MLIR][doc] Make summary appear different than discription

[rikhuijzer]

Summary

This patch aims to clarify which part of the docs is the summary and which
part is the description.

I did a preview of the output and think the suggested bold and italic style
is much clearer and looks reasonably nice.

I've considered also to enforce capitalization of the first letter of the
summary and ending with a dot (as discussed in
https://reviews.llvm.org/D151649), but it seems to me that the tradeoff in
extra test running time is not worth it. Currently, emitOpDoc is not
triggered for every summary during check-mlir.

[jpienaar]

I think there are only two tests for it, and none check anything much, so didn't quite follow the testing comment. I'd not be considered too much about efficiency here, it's not something that happens often and the time spent in the tool is rather low.

[rikhuijzer]

In D152621#4411358, @jpienaar wrote:

I think there are only two tests for it, and none check anything much, so didn't quite follow the testing comment. I'd not be considered too much about efficiency here, it's not something that happens often and the time spent in the tool is rather low.

Ah yes I understand the confusion. I meant that we could add a test to check-mlir which verifies all the summarys by running mlir-tblgen, but that sounded pretty computationally expensive to me for a reasonably trivial check.

[rikhuijzer]

Okay. Upon further inspection of the code and documentation, I've made a few mistakes with this patch:

1. Passes use a different logic for generating the documentation; which I didn't update to be in-line with this change.
2. Just like the documentation re-uses emitDescription internally for the generation, I should have defined and used emitSummary.
3. amx.tdpbssd shows **Summary:** __ meaning that apparently hasSummary does not guarantee a non-empty summary.
4. The **Summary:** is a bit verbose. Probably just making italic should be enough.
5. 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.

I'll soon make a patch to fix these things.

mlir/tools/mlir-tblgen/OpDocGen.cpp

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