diff --git a/mlir/docs/DefiningDialects/Operations.md b/mlir/docs/DefiningDialects/Operations.md --- a/mlir/docs/DefiningDialects/Operations.md +++ b/mlir/docs/DefiningDialects/Operations.md @@ -165,9 +165,10 @@ 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 --- a/mlir/tools/mlir-tblgen/DocGenUtilities.h +++ b/mlir/tools/mlir-tblgen/DocGenUtilities.h @@ -23,6 +23,10 @@ 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). // diff --git a/mlir/tools/mlir-tblgen/OpDocGen.cpp b/mlir/tools/mlir-tblgen/OpDocGen.cpp --- a/mlir/tools/mlir-tblgen/OpDocGen.cpp +++ b/mlir/tools/mlir-tblgen/OpDocGen.cpp @@ -37,6 +37,14 @@ 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). // @@ -160,7 +168,7 @@ // 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 --- a/mlir/tools/mlir-tblgen/PassDocGen.cpp +++ b/mlir/tools/mlir-tblgen/PassDocGen.cpp @@ -21,8 +21,8 @@ /// 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.