4acbd4446d
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
46 lines
1.6 KiB
C++
46 lines
1.6 KiB
C++
//===- DocGenUtilities.h - MLIR doc gen utilities ---------------*- C++ -*-===//
|
|
//
|
|
// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
|
|
// See https://llvm.org/LICENSE.txt for license information.
|
|
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
|
|
//
|
|
//===----------------------------------------------------------------------===//
|
|
//
|
|
// This file defines common utilities for generating documents from tablegen
|
|
// structures.
|
|
//
|
|
//===----------------------------------------------------------------------===//
|
|
|
|
#ifndef MLIR_TOOLS_MLIRTBLGEN_DOCGENUTILITIES_H_
|
|
#define MLIR_TOOLS_MLIRTBLGEN_DOCGENUTILITIES_H_
|
|
|
|
#include "llvm/ADT/StringRef.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_
|