xref: /llvm-project/mlir/tools/mlir-tblgen/OpDocGen.cpp (revision 468581f16bff35302e90c0dfb9e8978ceb8ea273) 
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 "OpGenHelpers.h"
16 #include "mlir/Support/IndentedOstream.h"
17 #include "mlir/TableGen/AttrOrTypeDef.h"
18 #include "mlir/TableGen/GenInfo.h"
19 #include "mlir/TableGen/Operator.h"
20 #include "llvm/ADT/DenseMap.h"
21 #include "llvm/ADT/StringExtras.h"
22 #include "llvm/Support/CommandLine.h"
23 #include "llvm/Support/FormatVariadic.h"
24 #include "llvm/Support/Regex.h"
25 #include "llvm/Support/Signals.h"
26 #include "llvm/TableGen/Error.h"
27 #include "llvm/TableGen/Record.h"
28 #include "llvm/TableGen/TableGenBackend.h"
29 
30 #include <set>
31 
32 using namespace llvm;
33 using namespace mlir;
34 using namespace mlir::tblgen;
35 
36 using mlir::tblgen::Operator;
37 
38 extern llvm::cl::opt<std::string> selectedDialect;
39 
40 // Emit the description by aligning the text to the left per line (e.g.,
41 // removing the minimum indentation across the block).
42 //
43 // This expects that the description in the tablegen file is already formatted
44 // in a way the user wanted but has some additional indenting due to being
45 // nested in the op definition.
46 void mlir::tblgen::emitDescription(StringRef description, raw_ostream &os) {
47   raw_indented_ostream ros(os);
48   ros.reindent(description.rtrim(" \t"));
49 }
50 
51 // Emits `str` with trailing newline if not empty.
52 static void emitIfNotEmpty(StringRef str, raw_ostream &os) {
53   if (!str.empty()) {
54     emitDescription(str, os);
55     os << "\n";
56   }
57 }
58 
59 /// Emit the given named constraint.
60 template <typename T>
61 static void emitNamedConstraint(const T &it, raw_ostream &os) {
62   if (!it.name.empty())
63     os << "| `" << it.name << "`";
64   else
65     os << "&laquo;unnamed&raquo;";
66   os << " | " << it.constraint.getSummary() << "\n";
67 }
68 
69 //===----------------------------------------------------------------------===//
70 // Operation Documentation
71 //===----------------------------------------------------------------------===//
72 
73 /// Emit the assembly format of an operation.
74 static void emitAssemblyFormat(StringRef opName, StringRef format,
75                                raw_ostream &os) {
76   os << "\nSyntax:\n\n```\noperation ::= `" << opName << "` ";
77 
78   // Print the assembly format aligned.
79   unsigned indent = strlen("operation ::= ");
80   std::pair<StringRef, StringRef> split = format.split('\n');
81   os << split.first.trim() << "\n";
82   do {
83     split = split.second.split('\n');
84     StringRef formatChunk = split.first.trim();
85     if (!formatChunk.empty())
86       os.indent(indent) << formatChunk << "\n";
87   } while (!split.second.empty());
88   os << "```\n\n";
89 }
90 
91 static void emitOpTraitsDoc(Operator op, raw_ostream &os) {
92   // TODO: We should link to the trait/documentation of it. That also means we
93   // should add descriptions to traits that can be queried.
94   // Collect using set to sort effects, interfaces & traits.
95   std::set<std::string> effects, interfaces, traits;
96   for (auto &trait : op.getTraits()) {
97     if (isa<PredTrait>(&trait))
98       continue;
99 
100     std::string name = trait.getDef().getName().str();
101     StringRef ref = name;
102     StringRef traitName = trait.getDef().getValueAsString("trait");
103     traitName.consume_back("::Trait");
104     traitName.consume_back("::Impl");
105     if (ref.startswith("anonymous_"))
106       name = traitName.str();
107     if (isa<InterfaceTrait>(&trait)) {
108       if (trait.getDef().isSubClassOf("SideEffectsTraitBase")) {
109         auto effectName = trait.getDef().getValueAsString("baseEffectName");
110         effectName.consume_front("::");
111         effectName.consume_front("mlir::");
112         std::string effectStr;
113         llvm::raw_string_ostream os(effectStr);
114         os << effectName << "{";
115         auto list = trait.getDef().getValueAsListOfDefs("effects");
116         llvm::interleaveComma(list, os, [&](Record *rec) {
117           StringRef effect = rec->getValueAsString("effect");
118           effect.consume_front("::");
119           effect.consume_front("mlir::");
120           os << effect << " on " << rec->getValueAsString("resource");
121         });
122         os << "}";
123         effects.insert(os.str());
124         name.append(llvm::formatv(" ({0})", traitName).str());
125       }
126       interfaces.insert(name);
127       continue;
128     }
129 
130     traits.insert(name);
131   }
132   if (!traits.empty()) {
133     llvm::interleaveComma(traits, os << "\nTraits: ");
134     os << "\n";
135   }
136   if (!interfaces.empty()) {
137     llvm::interleaveComma(interfaces, os << "\nInterfaces: ");
138     os << "\n";
139   }
140   if (!effects.empty()) {
141     llvm::interleaveComma(effects, os << "\nEffects: ");
142     os << "\n";
143   }
144 }
145 
146 static void emitOpDoc(Operator op, raw_ostream &os) {
147   os << llvm::formatv("### `{0}` ({1})\n", op.getOperationName(),
148                       op.getQualCppClassName());
149 
150   // Emit the summary, syntax, and description if present.
151   if (op.hasSummary())
152     os << "\n" << op.getSummary() << "\n\n";
153   if (op.hasAssemblyFormat())
154     emitAssemblyFormat(op.getOperationName(), op.getAssemblyFormat().trim(),
155                        os);
156   if (op.hasDescription())
157     mlir::tblgen::emitDescription(op.getDescription(), os);
158 
159   emitOpTraitsDoc(op, os);
160 
161   // Emit attributes.
162   if (op.getNumAttributes() != 0) {
163     // TODO: Attributes are only documented by TableGen name, with no further
164     // info. This should be improved.
165     os << "\n#### Attributes:\n\n";
166     os << "| Attribute | MLIR Type | Description |\n"
167        << "| :-------: | :-------: | ----------- |\n";
168     for (const auto &it : op.getAttributes()) {
169       StringRef storageType = it.attr.getStorageType();
170       os << "| `" << it.name << "` | " << storageType << " | "
171          << it.attr.getSummary() << "\n";
172     }
173   }
174 
175   // Emit each of the operands.
176   if (op.getNumOperands() != 0) {
177     os << "\n#### Operands:\n\n";
178     os << "| Operand | Description |\n"
179        << "| :-----: | ----------- |\n";
180     for (const auto &it : op.getOperands())
181       emitNamedConstraint(it, os);
182   }
183 
184   // Emit results.
185   if (op.getNumResults() != 0) {
186     os << "\n#### Results:\n\n";
187     os << "| Result | Description |\n"
188        << "| :----: | ----------- |\n";
189     for (const auto &it : op.getResults())
190       emitNamedConstraint(it, os);
191   }
192 
193   // Emit successors.
194   if (op.getNumSuccessors() != 0) {
195     os << "\n#### Successors:\n\n";
196     os << "| Successor | Description |\n"
197        << "| :-------: | ----------- |\n";
198     for (const auto &it : op.getSuccessors())
199       emitNamedConstraint(it, os);
200   }
201 
202   os << "\n";
203 }
204 
205 static void emitOpDoc(const RecordKeeper &recordKeeper, raw_ostream &os) {
206   auto opDefs = getRequestedOpDefinitions(recordKeeper);
207 
208   os << "<!-- Autogenerated by mlir-tblgen; don't manually edit -->\n";
209   for (const llvm::Record *opDef : opDefs)
210     emitOpDoc(Operator(opDef), os);
211 }
212 
213 //===----------------------------------------------------------------------===//
214 // Type Documentation
215 //===----------------------------------------------------------------------===//
216 
217 static void emitTypeDoc(const Type &type, raw_ostream &os) {
218   os << "### " << type.getSummary() << "\n";
219   emitDescription(type.getDescription(), os);
220   os << "\n";
221 }
222 
223 //===----------------------------------------------------------------------===//
224 // TypeDef Documentation
225 //===----------------------------------------------------------------------===//
226 
227 static void emitAttrOrTypeDefAssemblyFormat(const AttrOrTypeDef &def,
228                                             raw_ostream &os) {
229   SmallVector<AttrOrTypeParameter, 4> parameters;
230   def.getParameters(parameters);
231   if (parameters.empty()) {
232     os << "\nSyntax: `!" << def.getDialect().getName() << "."
233        << def.getMnemonic() << "`\n";
234     return;
235   }
236 
237   os << "\nSyntax:\n\n```\n!" << def.getDialect().getName() << "."
238      << def.getMnemonic() << "<\n";
239   for (auto it : llvm::enumerate(parameters)) {
240     const AttrOrTypeParameter &param = it.value();
241     os << "  " << param.getSyntax();
242     if (it.index() < (parameters.size() - 1))
243       os << ",";
244     os << "   # " << param.getName() << "\n";
245   }
246   os << ">\n```\n";
247 }
248 
249 static void emitAttrOrTypeDefDoc(const AttrOrTypeDef &def, raw_ostream &os) {
250   os << llvm::formatv("### {0}\n", def.getCppClassName());
251 
252   // Emit the summary if present.
253   if (def.hasSummary())
254     os << "\n" << def.getSummary() << "\n";
255 
256   // Emit the syntax if present.
257   if (def.getMnemonic() && def.getPrinterCode() == StringRef() &&
258       def.getParserCode() == StringRef())
259     emitAttrOrTypeDefAssemblyFormat(def, os);
260 
261   // Emit the description if present.
262   if (def.hasDescription()) {
263     os << "\n";
264     mlir::tblgen::emitDescription(def.getDescription(), os);
265   }
266 
267   // Emit parameter documentation.
268   SmallVector<AttrOrTypeParameter, 4> parameters;
269   def.getParameters(parameters);
270   if (!parameters.empty()) {
271     os << "\n#### Parameters:\n\n";
272     os << "| Parameter | C++ type | Description |\n"
273        << "| :-------: | :-------: | ----------- |\n";
274     for (const auto &it : parameters) {
275       auto desc = it.getSummary();
276       os << "| " << it.getName() << " | `" << it.getCppType() << "` | "
277          << (desc ? *desc : "") << " |\n";
278     }
279   }
280 
281   os << "\n";
282 }
283 
284 static void emitAttrOrTypeDefDoc(const RecordKeeper &recordKeeper,
285                                  raw_ostream &os, StringRef recordTypeName) {
286   std::vector<llvm::Record *> defs =
287       recordKeeper.getAllDerivedDefinitions(recordTypeName);
288 
289   os << "<!-- Autogenerated by mlir-tblgen; don't manually edit -->\n";
290   for (const llvm::Record *def : defs)
291     emitAttrOrTypeDefDoc(AttrOrTypeDef(def), os);
292 }
293 
294 //===----------------------------------------------------------------------===//
295 // Dialect Documentation
296 //===----------------------------------------------------------------------===//
297 
298 static void emitDialectDoc(const Dialect &dialect, ArrayRef<AttrDef> attrDefs,
299                            ArrayRef<Operator> ops, ArrayRef<Type> types,
300                            ArrayRef<TypeDef> typeDefs, raw_ostream &os) {
301   if (selectedDialect.getNumOccurrences() &&
302       dialect.getName() != selectedDialect)
303     return;
304   os << "# '" << dialect.getName() << "' Dialect\n\n";
305   emitIfNotEmpty(dialect.getSummary(), os);
306   emitIfNotEmpty(dialect.getDescription(), os);
307 
308   // Generate a TOC marker except if description already contains one.
309   llvm::Regex r("^[[:space:]]*\\[TOC\\]$", llvm::Regex::RegexFlags::Newline);
310   if (!r.match(dialect.getDescription()))
311     os << "[TOC]\n\n";
312 
313   if (!attrDefs.empty()) {
314     os << "## Attribute definition\n\n";
315     for (const AttrDef &def : attrDefs)
316       emitAttrOrTypeDefDoc(def, os);
317   }
318 
319   // TODO: Add link between use and def for types
320   if (!types.empty()) {
321     os << "## Type constraint definition\n\n";
322     for (const Type &type : types)
323       emitTypeDoc(type, os);
324   }
325 
326   if (!ops.empty()) {
327     os << "## Operation definition\n\n";
328     for (const Operator &op : ops)
329       emitOpDoc(op, os);
330   }
331 
332   if (!typeDefs.empty()) {
333     os << "## Type definition\n\n";
334     for (const TypeDef &def : typeDefs)
335       emitAttrOrTypeDefDoc(def, os);
336   }
337 }
338 
339 static void emitDialectDoc(const RecordKeeper &recordKeeper, raw_ostream &os) {
340   std::vector<Record *> opDefs = getRequestedOpDefinitions(recordKeeper);
341   std::vector<Record *> typeDefs =
342       recordKeeper.getAllDerivedDefinitions("DialectType");
343   std::vector<Record *> typeDefDefs =
344       recordKeeper.getAllDerivedDefinitions("TypeDef");
345   std::vector<Record *> attrDefDefs =
346       recordKeeper.getAllDerivedDefinitions("AttrDef");
347 
348   std::set<Dialect> dialectsWithDocs;
349 
350   llvm::StringMap<std::vector<AttrDef>> dialectAttrDefs;
351   llvm::StringMap<std::vector<Operator>> dialectOps;
352   llvm::StringMap<std::vector<Type>> dialectTypes;
353   llvm::StringMap<std::vector<TypeDef>> dialectTypeDefs;
354   for (auto *attrDef : attrDefDefs) {
355     AttrDef attr(attrDef);
356     dialectAttrDefs[attr.getDialect().getName()].push_back(attr);
357     dialectsWithDocs.insert(attr.getDialect());
358   }
359   for (auto *opDef : opDefs) {
360     Operator op(opDef);
361     dialectOps[op.getDialect().getName()].push_back(op);
362     dialectsWithDocs.insert(op.getDialect());
363   }
364   for (auto *typeDef : typeDefs) {
365     Type type(typeDef);
366     if (auto dialect = type.getDialect())
367       dialectTypes[dialect.getName()].push_back(type);
368   }
369   for (auto *typeDef : typeDefDefs) {
370     TypeDef type(typeDef);
371     dialectTypeDefs[type.getDialect().getName()].push_back(type);
372     dialectsWithDocs.insert(type.getDialect());
373   }
374 
375   os << "<!-- Autogenerated by mlir-tblgen; don't manually edit -->\n";
376   for (const Dialect &dialect : dialectsWithDocs) {
377     StringRef dialectName = dialect.getName();
378     emitDialectDoc(dialect, dialectAttrDefs[dialectName],
379                    dialectOps[dialectName], dialectTypes[dialectName],
380                    dialectTypeDefs[dialectName], os);
381   }
382 }
383 
384 //===----------------------------------------------------------------------===//
385 // Gen Registration
386 //===----------------------------------------------------------------------===//
387 
388 static mlir::GenRegistration
389     genAttrRegister("gen-attrdef-doc",
390                     "Generate dialect attribute documentation",
391                     [](const RecordKeeper &records, raw_ostream &os) {
392                       emitAttrOrTypeDefDoc(records, os, "AttrDef");
393                       return false;
394                     });
395 
396 static mlir::GenRegistration
397     genOpRegister("gen-op-doc", "Generate dialect documentation",
398                   [](const RecordKeeper &records, raw_ostream &os) {
399                     emitOpDoc(records, os);
400                     return false;
401                   });
402 
403 static mlir::GenRegistration
404     genTypeRegister("gen-typedef-doc", "Generate dialect type documentation",
405                     [](const RecordKeeper &records, raw_ostream &os) {
406                       emitAttrOrTypeDefDoc(records, os, "TypeDef");
407                       return false;
408                     });
409 
410 static mlir::GenRegistration
411     genRegister("gen-dialect-doc", "Generate dialect documentation",
412                 [](const RecordKeeper &records, raw_ostream &os) {
413                   emitDialectDoc(records, os);
414                   return false;
415                 });
416