[Mlir-commits] [mlir] 4acbd44 - [MLIR][Doc] Also print `summary`s for passes on a newline
llvmlistbot at llvm.org
llvmlistbot at llvm.org
Tue Jun 13 00:26:18 PDT 2023
Author: rikhuijzer
Date: 2023-06-13T09:26:11+02:00
New Revision: 4acbd4446dbbedd49ea89fdf420a03b338642051
URL: https://github.com/llvm/llvm-project/commit/4acbd4446dbbedd49ea89fdf420a03b338642051
DIFF: https://github.com/llvm/llvm-project/commit/4acbd4446dbbedd49ea89fdf420a03b338642051.diff
LOG: [MLIR][Doc] Also print `summary`s for passes on a newline
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.
Reviewed By: jpienaar
Differential Revision: https://reviews.llvm.org/D152648
Added:
Modified:
mlir/docs/DefiningDialects/Operations.md
mlir/tools/mlir-tblgen/DocGenUtilities.h
mlir/tools/mlir-tblgen/OpDocGen.cpp
mlir/tools/mlir-tblgen/PassDocGen.cpp
Removed:
################################################################################
diff --git a/mlir/docs/DefiningDialects/Operations.md b/mlir/docs/DefiningDialects/Operations.md
index 1411a9f239c1b..b27330319f659 100644
--- a/mlir/docs/DefiningDialects/Operations.md
+++ b/mlir/docs/DefiningDialects/Operations.md
@@ -165,9 +165,10 @@ let description = [{
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
diff --git a/mlir/tools/mlir-tblgen/DocGenUtilities.h b/mlir/tools/mlir-tblgen/DocGenUtilities.h
index a1fbbb3c3e11e..dd1dbbe243911 100644
--- a/mlir/tools/mlir-tblgen/DocGenUtilities.h
+++ b/mlir/tools/mlir-tblgen/DocGenUtilities.h
@@ -23,6 +23,10 @@ class raw_ostream;
namespace mlir {
namespace tblgen {
+// Emit the summary. To avoid confusion, the summary is styled
diff erently 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).
//
diff --git a/mlir/tools/mlir-tblgen/OpDocGen.cpp b/mlir/tools/mlir-tblgen/OpDocGen.cpp
index 8264b0afe684d..cac1c8d993876 100644
--- a/mlir/tools/mlir-tblgen/OpDocGen.cpp
+++ b/mlir/tools/mlir-tblgen/OpDocGen.cpp
@@ -47,6 +47,14 @@ 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).
//
@@ -172,7 +180,7 @@ static void emitOpDoc(const Operator &op, raw_ostream &os) {
// 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);
diff --git a/mlir/tools/mlir-tblgen/PassDocGen.cpp b/mlir/tools/mlir-tblgen/PassDocGen.cpp
index c4ebafc4893eb..8febba1915625 100644
--- a/mlir/tools/mlir-tblgen/PassDocGen.cpp
+++ b/mlir/tools/mlir-tblgen/PassDocGen.cpp
@@ -21,8 +21,8 @@ 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.
More information about the Mlir-commits
mailing list