Auto-generate comments for dialect ops. (GPUOpen-Drivers#118)

Currently, the summary and description fields for dialect ops remain
unused. Add those as comment above the class declaration.

Author: tsymalla

example/ExampleDialect.td

@@ -320,3 +320,19 @@ def StringAttrOp : Op<ExampleDialect, "string.attr.op", [WillReturn]> {
     The argument should not have a setter method
   }];
 }
+
+def NoSummaryOp : Op<ExampleDialect, "no.summary.op", [WillReturn]> {
+  let results = (outs);
+  let arguments = (ins);
+
+  let description = [{
+    Some description
+  }];
+}
+
+def NoDescriptionOp : Op<ExampleDialect, "no.description.op", [WillReturn]> {
+  let results = (outs);
+  let arguments = (ins);
+
+  let summary = "Some summary";
+}

include/llvm-dialects/TableGen/Common.h

@@ -20,6 +20,7 @@
 
 #include "llvm/Support/raw_ostream.h"
 #include "llvm/TableGen/Record.h"
+#include <string>
 
 #if !defined(LLVM_MAIN_REVISION) || LLVM_MAIN_REVISION >= 513628
 using RecordKeeperTy = const llvm::RecordKeeper;
@@ -35,4 +36,8 @@ void emitHeader(llvm::raw_ostream& out);
 
 bool shouldEmitComments();
 
+/// Prefix an incoming multi-line string with a single-line comment string line
+/// by line.
+std::string createCommentFromString(const std::string &input);
+
 } // namespace llvm_dialects

include/llvm-dialects/TableGen/Operations.h

@@ -103,6 +103,8 @@ class Operation : public OperationBase {
 public:
   std::string name;
   std::string mnemonic;
+  std::string summary;
+  std::string description;
   std::vector<Trait *> traits;
 
   std::vector<NamedValue> results;

lib/TableGen/Common.cpp

@@ -17,6 +17,8 @@
  */
 
 #include "llvm-dialects/TableGen/Common.h"
+#include "llvm/ADT/SmallVector.h"
+#include "llvm/ADT/StringRef.h"
 
 #include "llvm/Support/CommandLine.h"
 
@@ -33,3 +35,18 @@ void llvm_dialects::emitHeader(raw_ostream& out) {
 }
 
 bool llvm_dialects::shouldEmitComments() { return g_emitComments; }
+
+std::string llvm_dialects::createCommentFromString(const std::string &input) {
+  StringRef inRef{input};
+  if (inRef.trim().empty())
+    return input;
+
+  SmallVector<StringRef> lines;
+  inRef.split(lines, '\n');
+
+  std::string outStr;
+  for (auto line : lines)
+    outStr += "/// " + line.str() + '\n';
+
+  return outStr;
+}

lib/TableGen/GenDialect.cpp

@@ -172,7 +172,16 @@ class Builder;
     fmt.withOp(op.name);
     fmt.addSubst("mnemonic", op.mnemonic);
 
+    std::string description = "/// " + op.name + '\n';
+
+    if (!op.summary.empty())
+      description += createCommentFromString(op.summary);
+
+    if (!op.description.empty())
+      description += createCommentFromString(op.description);
+
     out << tgfmt(R"(
+      $2
       class $_op : public $0 {
         static const ::llvm::StringLiteral s_name; //{"$dialect.$mnemonic"};
 
@@ -188,7 +197,8 @@ class Builder;
                  &fmt,
                  op.superclass() ? op.superclass()->name : "::llvm::CallInst",
                  !op.haveResultOverloads() ? "isSimpleOperation"
-                                           : "isOverloadedOperation");
+                                           : "isOverloadedOperation",
+                 description);
 
     for (const auto &builder : op.builders())
       builder.emitDeclaration(out, fmt);

lib/TableGen/Operations.cpp

@@ -360,6 +360,11 @@ bool Operation::parse(raw_ostream &errs, GenDialectsContext *context,
 
   op->name = record->getName();
   op->mnemonic = record->getValueAsString("mnemonic");
+  if (!record->isValueUnset("summary"))
+    op->summary = record->getValueAsString("summary");
+
+  if (!record->isValueUnset("description"))
+    op->description = record->getValueAsString("description");
   for (RecordTy *traitRec : record->getValueAsListOfDefs("traits"))
     op->traits.push_back(context->getTrait(traitRec));
 

test/example/generated/ExampleDialect.cpp.inc

@@ -112,6 +112,16 @@ namespace xd::cpp {
             state.setError();
         });
 
+        builder.add<NoDescriptionOp>([](::llvm_dialects::VerifierState &state, NoDescriptionOp &op) {
+          if (!op.verifier(state.out()))
+            state.setError();
+        });
+      
+        builder.add<NoSummaryOp>([](::llvm_dialects::VerifierState &state, NoSummaryOp &op) {
+          if (!op.verifier(state.out()))
+            state.setError();
+        });
+      
         builder.add<ReadOp>([](::llvm_dialects::VerifierState &state, ReadOp &op) {
           if (!op.verifier(state.out()))
             state.setError();
@@ -1519,6 +1529,108 @@ instName
 
 
 
+      const ::llvm::StringLiteral NoDescriptionOp::s_name{"xd.ir.no.description.op"};
+
+    NoDescriptionOp* NoDescriptionOp::create(llvm_dialects::Builder& b, const llvm::Twine &instName) {
+    ::llvm::LLVMContext& context = b.getContext();
+    (void)context;
+    ::llvm::Module& module = *b.GetInsertBlock()->getModule();
+  
+  
+      const ::llvm::AttributeList attrs
+          = ExampleDialect::get(context).getAttributeList(4);
+    auto fnType = ::llvm::FunctionType::get(::llvm::Type::getVoidTy(context), {
+}, false);
+
+    auto fn = module.getOrInsertFunction(s_name, fnType, attrs);
+    ::llvm::SmallString<32> newName;
+    for (unsigned i = 0; !::llvm::isa<::llvm::Function>(fn.getCallee()) ||
+                         ::llvm::cast<::llvm::Function>(fn.getCallee())->getFunctionType() != fn.getFunctionType(); i++) {
+      // If a function with the same name but a different types already exists,
+      // we get a bitcast of a function or a function with the wrong type.
+      // Try new names until we get one with the correct type.
+      newName = "";
+      ::llvm::raw_svector_ostream newNameStream(newName);
+      newNameStream << s_name << "_" << i;
+      fn = module.getOrInsertFunction(newNameStream.str(), fnType, attrs);
+    }
+    assert(::llvm::isa<::llvm::Function>(fn.getCallee()));
+    assert(fn.getFunctionType() == fnType);
+    assert(::llvm::cast<::llvm::Function>(fn.getCallee())->getFunctionType() == fn.getFunctionType());
+
+  return ::llvm::cast<NoDescriptionOp>(b.CreateCall(fn, std::nullopt, instName));
+}
+
+
+    bool NoDescriptionOp::verifier(::llvm::raw_ostream &errs) {
+      ::llvm::LLVMContext &context = getModule()->getContext();
+      (void)context;
+
+      using ::llvm_dialects::printable;
+  
+      if (arg_size() != 0) {
+        errs << "  wrong number of arguments: " << arg_size()
+               << ", expected 0\n";
+        return false;
+      }
+    return true;
+}
+
+
+
+
+
+      const ::llvm::StringLiteral NoSummaryOp::s_name{"xd.ir.no.summary.op"};
+
+    NoSummaryOp* NoSummaryOp::create(llvm_dialects::Builder& b, const llvm::Twine &instName) {
+    ::llvm::LLVMContext& context = b.getContext();
+    (void)context;
+    ::llvm::Module& module = *b.GetInsertBlock()->getModule();
+  
+  
+      const ::llvm::AttributeList attrs
+          = ExampleDialect::get(context).getAttributeList(4);
+    auto fnType = ::llvm::FunctionType::get(::llvm::Type::getVoidTy(context), {
+}, false);
+
+    auto fn = module.getOrInsertFunction(s_name, fnType, attrs);
+    ::llvm::SmallString<32> newName;
+    for (unsigned i = 0; !::llvm::isa<::llvm::Function>(fn.getCallee()) ||
+                         ::llvm::cast<::llvm::Function>(fn.getCallee())->getFunctionType() != fn.getFunctionType(); i++) {
+      // If a function with the same name but a different types already exists,
+      // we get a bitcast of a function or a function with the wrong type.
+      // Try new names until we get one with the correct type.
+      newName = "";
+      ::llvm::raw_svector_ostream newNameStream(newName);
+      newNameStream << s_name << "_" << i;
+      fn = module.getOrInsertFunction(newNameStream.str(), fnType, attrs);
+    }
+    assert(::llvm::isa<::llvm::Function>(fn.getCallee()));
+    assert(fn.getFunctionType() == fnType);
+    assert(::llvm::cast<::llvm::Function>(fn.getCallee())->getFunctionType() == fn.getFunctionType());
+
+  return ::llvm::cast<NoSummaryOp>(b.CreateCall(fn, std::nullopt, instName));
+}
+
+
+    bool NoSummaryOp::verifier(::llvm::raw_ostream &errs) {
+      ::llvm::LLVMContext &context = getModule()->getContext();
+      (void)context;
+
+      using ::llvm_dialects::printable;
+  
+      if (arg_size() != 0) {
+        errs << "  wrong number of arguments: " << arg_size()
+               << ", expected 0\n";
+        return false;
+      }
+    return true;
+}
+
+
+
+
+
       const ::llvm::StringLiteral ReadOp::s_name{"xd.ir.read"};
 
     ReadOp* ReadOp::create(llvm_dialects::Builder& b, ::llvm::Type* dataType, const llvm::Twine &instName) {
@@ -2357,6 +2469,22 @@ data
       }
 
 
+      template <>
+      const ::llvm_dialects::OpDescription &
+      ::llvm_dialects::OpDescription::get<xd::cpp::NoDescriptionOp>() {
+        static const ::llvm_dialects::OpDescription desc{false, "xd.ir.no.description.op"};
+        return desc;
+      }
+
+    
+      template <>
+      const ::llvm_dialects::OpDescription &
+      ::llvm_dialects::OpDescription::get<xd::cpp::NoSummaryOp>() {
+        static const ::llvm_dialects::OpDescription desc{false, "xd.ir.no.summary.op"};
+        return desc;
+      }
+
+    
       template <>
       const ::llvm_dialects::OpDescription &
       ::llvm_dialects::OpDescription::get<xd::cpp::ReadOp>() {