1 //===- OpDocGen.cpp - MLIR operation 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 // OpDocGen uses the description of operations to generate documentation for the 10 // operations. 11 // 12 //===----------------------------------------------------------------------===// 13 14 #include "DocGenUtilities.h" 15 #include "mlir/Support/IndentedOstream.h" 16 #include "mlir/TableGen/GenInfo.h" 17 #include "mlir/TableGen/Operator.h" 18 #include "mlir/TableGen/TypeDef.h" 19 #include "llvm/ADT/DenseMap.h" 20 #include "llvm/ADT/StringExtras.h" 21 #include "llvm/Support/FormatVariadic.h" 22 #include "llvm/Support/Signals.h" 23 #include "llvm/TableGen/Error.h" 24 #include "llvm/TableGen/Record.h" 25 #include "llvm/TableGen/TableGenBackend.h" 26 27 #include <set> 28 29 using namespace llvm; 30 using namespace mlir; 31 using namespace mlir::tblgen; 32 33 using mlir::tblgen::Operator; 34 35 // Emit the description by aligning the text to the left per line (e.g., 36 // removing the minimum indentation across the block). 37 // 38 // This expects that the description in the tablegen file is already formatted 39 // in a way the user wanted but has some additional indenting due to being 40 // nested in the op definition. 41 void mlir::tblgen::emitDescription(StringRef description, raw_ostream &os) { 42 raw_indented_ostream ros(os); 43 ros.reindent(description.rtrim(" \t")); 44 } 45 46 // Emits `str` with trailing newline if not empty. 47 static void emitIfNotEmpty(StringRef str, raw_ostream &os) { 48 if (!str.empty()) { 49 emitDescription(str, os); 50 os << "\n"; 51 } 52 } 53 54 /// Emit the given named constraint. 55 template <typename T> 56 static void emitNamedConstraint(const T &it, raw_ostream &os) { 57 if (!it.name.empty()) 58 os << "`" << it.name << "`"; 59 else 60 os << "«unnamed»"; 61 os << " | " << it.constraint.getSummary() << "\n"; 62 } 63 64 //===----------------------------------------------------------------------===// 65 // Operation Documentation 66 //===----------------------------------------------------------------------===// 67 68 /// Emit the assembly format of an operation. 69 static void emitAssemblyFormat(StringRef opName, StringRef format, 70 raw_ostream &os) { 71 os << "\nSyntax:\n\n```\noperation ::= `" << opName << "` "; 72 73 // Print the assembly format aligned. 74 unsigned indent = strlen("operation ::= "); 75 std::pair<StringRef, StringRef> split = format.split('\n'); 76 os << split.first.trim() << "\n"; 77 do { 78 split = split.second.split('\n'); 79 StringRef formatChunk = split.first.trim(); 80 if (!formatChunk.empty()) 81 os.indent(indent) << formatChunk << "\n"; 82 } while (!split.second.empty()); 83 os << "```\n\n"; 84 } 85 86 static void emitOpDoc(Operator op, raw_ostream &os) { 87 os << llvm::formatv("### `{0}` ({1})\n", op.getOperationName(), 88 op.getQualCppClassName()); 89 90 // Emit the summary, syntax, and description if present. 91 if (op.hasSummary()) 92 os << "\n" << op.getSummary() << "\n\n"; 93 if (op.hasAssemblyFormat()) 94 emitAssemblyFormat(op.getOperationName(), op.getAssemblyFormat().trim(), 95 os); 96 if (op.hasDescription()) 97 mlir::tblgen::emitDescription(op.getDescription(), os); 98 99 // Emit attributes. 100 if (op.getNumAttributes() != 0) { 101 // TODO: Attributes are only documented by TableGen name, with no further 102 // info. This should be improved. 103 os << "\n#### Attributes:\n\n"; 104 os << "| Attribute | MLIR Type | Description |\n" 105 << "| :-------: | :-------: | ----------- |\n"; 106 for (const auto &it : op.getAttributes()) { 107 StringRef storageType = it.attr.getStorageType(); 108 os << "`" << it.name << "` | " << storageType << " | " 109 << it.attr.getSummary() << "\n"; 110 } 111 } 112 113 // Emit each of the operands. 114 if (op.getNumOperands() != 0) { 115 os << "\n#### Operands:\n\n"; 116 os << "| Operand | Description |\n" 117 << "| :-----: | ----------- |\n"; 118 for (const auto &it : op.getOperands()) 119 emitNamedConstraint(it, os); 120 } 121 122 // Emit results. 123 if (op.getNumResults() != 0) { 124 os << "\n#### Results:\n\n"; 125 os << "| Result | Description |\n" 126 << "| :----: | ----------- |\n"; 127 for (const auto &it : op.getResults()) 128 emitNamedConstraint(it, os); 129 } 130 131 // Emit successors. 132 if (op.getNumSuccessors() != 0) { 133 os << "\n#### Successors:\n\n"; 134 os << "| Successor | Description |\n" 135 << "| :-------: | ----------- |\n"; 136 for (const auto &it : op.getSuccessors()) 137 emitNamedConstraint(it, os); 138 } 139 140 os << "\n"; 141 } 142 143 static void emitOpDoc(const RecordKeeper &recordKeeper, raw_ostream &os) { 144 auto opDefs = recordKeeper.getAllDerivedDefinitions("Op"); 145 146 os << "<!-- Autogenerated by mlir-tblgen; don't manually edit -->\n"; 147 for (const llvm::Record *opDef : opDefs) 148 emitOpDoc(Operator(opDef), os); 149 } 150 151 //===----------------------------------------------------------------------===// 152 // Type Documentation 153 //===----------------------------------------------------------------------===// 154 155 static void emitTypeDoc(const Type &type, raw_ostream &os) { 156 os << "### " << type.getSummary() << "\n"; 157 emitDescription(type.getDescription(), os); 158 os << "\n"; 159 } 160 161 //===----------------------------------------------------------------------===// 162 // TypeDef Documentation 163 //===----------------------------------------------------------------------===// 164 165 /// Emit the assembly format of a type. 166 static void emitTypeAssemblyFormat(TypeDef td, raw_ostream &os) { 167 SmallVector<TypeParameter, 4> parameters; 168 td.getParameters(parameters); 169 if (parameters.size() == 0) { 170 os << "\nSyntax: `!" << td.getDialect().getName() << "." << td.getMnemonic() 171 << "`\n"; 172 return; 173 } 174 175 os << "\nSyntax:\n\n```\n!" << td.getDialect().getName() << "." 176 << td.getMnemonic() << "<\n"; 177 for (auto *it = parameters.begin(), *e = parameters.end(); it < e; ++it) { 178 os << " " << it->getSyntax(); 179 if (it < parameters.end() - 1) 180 os << ","; 181 os << " # " << it->getName() << "\n"; 182 } 183 os << ">\n```\n"; 184 } 185 186 static void emitTypeDefDoc(TypeDef td, raw_ostream &os) { 187 os << llvm::formatv("### `{0}` ({1})\n", td.getName(), td.getCppClassName()); 188 189 // Emit the summary, syntax, and description if present. 190 if (td.hasSummary()) 191 os << "\n" << td.getSummary() << "\n"; 192 if (td.getMnemonic() && td.getPrinterCode() && *td.getPrinterCode() == "" && 193 td.getParserCode() && *td.getParserCode() == "") 194 emitTypeAssemblyFormat(td, os); 195 if (td.hasDescription()) { 196 os << "\n"; 197 mlir::tblgen::emitDescription(td.getDescription(), os); 198 } 199 200 // Emit attribute documentation. 201 SmallVector<TypeParameter, 4> parameters; 202 td.getParameters(parameters); 203 if (!parameters.empty()) { 204 os << "\n#### Type parameters:\n\n"; 205 os << "| Parameter | C++ type | Description |\n" 206 << "| :-------: | :-------: | ----------- |\n"; 207 for (const auto &it : parameters) { 208 auto desc = it.getSummary(); 209 os << "| " << it.getName() << " | `" << it.getCppType() << "` | " 210 << (desc ? *desc : "") << " |\n"; 211 } 212 } 213 214 os << "\n"; 215 } 216 217 //===----------------------------------------------------------------------===// 218 // Dialect Documentation 219 //===----------------------------------------------------------------------===// 220 221 static void emitDialectDoc(const Dialect &dialect, ArrayRef<Operator> ops, 222 ArrayRef<Type> types, ArrayRef<TypeDef> typeDefs, 223 raw_ostream &os) { 224 os << "# '" << dialect.getName() << "' Dialect\n\n"; 225 emitIfNotEmpty(dialect.getSummary(), os); 226 emitIfNotEmpty(dialect.getDescription(), os); 227 228 os << "[TOC]\n\n"; 229 230 // TODO: Add link between use and def for types 231 if (!types.empty()) { 232 os << "## Type constraint definition\n\n"; 233 for (const Type &type : types) 234 emitTypeDoc(type, os); 235 } 236 237 if (!ops.empty()) { 238 os << "## Operation definition\n\n"; 239 for (const Operator &op : ops) 240 emitOpDoc(op, os); 241 } 242 243 if (!typeDefs.empty()) { 244 os << "## Type definition\n\n"; 245 for (const TypeDef &td : typeDefs) 246 emitTypeDefDoc(td, os); 247 } 248 } 249 250 static void emitDialectDoc(const RecordKeeper &recordKeeper, raw_ostream &os) { 251 const auto &opDefs = recordKeeper.getAllDerivedDefinitions("Op"); 252 const auto &typeDefs = recordKeeper.getAllDerivedDefinitions("DialectType"); 253 const auto &typeDefDefs = recordKeeper.getAllDerivedDefinitions("TypeDef"); 254 255 std::set<Dialect> dialectsWithDocs; 256 std::map<Dialect, std::vector<Operator>> dialectOps; 257 std::map<Dialect, std::vector<Type>> dialectTypes; 258 std::map<Dialect, std::vector<TypeDef>> dialectTypeDefs; 259 for (auto *opDef : opDefs) { 260 Operator op(opDef); 261 dialectOps[op.getDialect()].push_back(op); 262 dialectsWithDocs.insert(op.getDialect()); 263 } 264 for (auto *typeDef : typeDefs) { 265 Type type(typeDef); 266 if (auto dialect = type.getDialect()) 267 dialectTypes[dialect].push_back(type); 268 } 269 for (auto *typeDef : typeDefDefs) { 270 TypeDef type(typeDef); 271 dialectTypeDefs[type.getDialect()].push_back(type); 272 dialectsWithDocs.insert(type.getDialect()); 273 } 274 275 os << "<!-- Autogenerated by mlir-tblgen; don't manually edit -->\n"; 276 for (auto dialect : dialectsWithDocs) 277 emitDialectDoc(dialect, dialectOps[dialect], dialectTypes[dialect], 278 dialectTypeDefs[dialect], os); 279 } 280 281 //===----------------------------------------------------------------------===// 282 // Gen Registration 283 //===----------------------------------------------------------------------===// 284 285 static mlir::GenRegistration 286 genOpRegister("gen-op-doc", "Generate dialect documentation", 287 [](const RecordKeeper &records, raw_ostream &os) { 288 emitOpDoc(records, os); 289 return false; 290 }); 291 292 static mlir::GenRegistration 293 genRegister("gen-dialect-doc", "Generate dialect documentation", 294 [](const RecordKeeper &records, raw_ostream &os) { 295 emitDialectDoc(records, os); 296 return false; 297 }); 298