1//===- PassDocGen.cpp - MLIR pass documentation generator -----------------===//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8//
9// PassDocGen uses the description of passes to generate documentation.
10//
11//===----------------------------------------------------------------------===//
12
13#include "DocGenUtilities.h"
14#include "mlir/TableGen/GenInfo.h"
15#include "mlir/TableGen/Pass.h"
16#include "llvm/Support/FormatVariadic.h"
17#include "llvm/TableGen/Record.h"
18
19using namespace mlir;
20using namespace mlir::tblgen;
21using llvm::RecordKeeper;
22
23/// Emit the documentation for the given pass.
24static void emitDoc(const Pass &pass, raw_ostream &os) {
25 os << llvm::formatv(Fmt: "\n### `-{0}`\n", Vals: pass.getArgument());
26 emitSummary(summary: pass.getSummary(), os);
27 emitDescription(description: pass.getDescription(), os);
28
29 // Handle the options of the pass.
30 ArrayRef<PassOption> options = pass.getOptions();
31 if (!options.empty()) {
32 os << "\n#### Options\n\n```\n";
33 size_t longestOption = 0;
34 for (const PassOption &option : options)
35 longestOption = std::max(a: option.getArgument().size(), b: longestOption);
36 for (const PassOption &option : options) {
37 os << "-" << option.getArgument();
38 os.indent(NumSpaces: longestOption - option.getArgument().size())
39 << " : " << option.getDescription() << "\n";
40 }
41 os << "```\n";
42 }
43
44 // Handle the statistics of the pass.
45 ArrayRef<PassStatistic> stats = pass.getStatistics();
46 if (!stats.empty()) {
47 os << "\n#### Statistics\n\n```\n";
48 size_t longestStat = 0;
49 for (const PassStatistic &stat : stats)
50 longestStat = std::max(a: stat.getName().size(), b: longestStat);
51 for (const PassStatistic &stat : stats) {
52 os << stat.getName();
53 os.indent(NumSpaces: longestStat - stat.getName().size())
54 << " : " << stat.getDescription() << "\n";
55 }
56 os << "```\n";
57 }
58}
59
60static void emitDocs(const RecordKeeper &records, raw_ostream &os) {
61 os << "<!-- Autogenerated by mlir-tblgen; don't manually edit -->\n";
62 auto passDefs = records.getAllDerivedDefinitions(ClassName: "PassBase");
63
64 // Collect the registered passes, sorted by argument name.
65 SmallVector<Pass, 16> passes(passDefs.begin(), passDefs.end());
66 SmallVector<Pass *, 16> sortedPasses(llvm::make_pointer_range(Range&: passes));
67 llvm::array_pod_sort(Start: sortedPasses.begin(), End: sortedPasses.end(),
68 Compare: [](Pass *const *lhs, Pass *const *rhs) {
69 return (*lhs)->getArgument().compare(
70 RHS: (*rhs)->getArgument());
71 });
72 for (Pass *pass : sortedPasses)
73 emitDoc(pass: *pass, os);
74}
75
76static mlir::GenRegistration
77 genRegister("gen-pass-doc", "Generate pass documentation",
78 [](const RecordKeeper &records, raw_ostream &os) {
79 emitDocs(records, os);
80 return false;
81 });
82

source code of mlir/tools/mlir-tblgen/PassDocGen.cpp