From a759cf3190b33291d457b097b30d5137716ca86f Mon Sep 17 00:00:00 2001
From: Lei Zhang <antiagainst@google.com>
Date: Tue, 29 Jan 2019 10:28:56 -0800
Subject: [PATCH] Include op results in generate TensorFlow/TFLite op docs

* Emitted result lists for ops.
* Changed to allow empty summary and description for ops.
* Avoided indenting description to allow proper MarkDown rendering of
  formatting markers inside description content.
* Used fixed width font for operand/attribute names.
* Massaged TensorFlow op docs and generated dialect op doc.

PiperOrigin-RevId: 231427574
---
 mlir/include/mlir/IR/op_base.td     |  4 ++--
 mlir/tools/mlir-tblgen/OpDocGen.cpp | 35 ++++++++++++++++++++---------
 2 files changed, 27 insertions(+), 12 deletions(-)

diff --git a/mlir/include/mlir/IR/op_base.td b/mlir/include/mlir/IR/op_base.td
index a128ae9dd96e..3958d6e96ead 100644
--- a/mlir/include/mlir/IR/op_base.td
+++ b/mlir/include/mlir/IR/op_base.td
@@ -352,10 +352,10 @@ class Op<string mnemonic, list<OpProperty> props = []> {
   string opName = mnemonic;
 
   // One-line human-readable description of what the op does.
-  string summary = ?;
+  string summary = "";
 
   // Additional, longer human-readable description of what the op does.
-  string description = ?;
+  string description = "";
 
   // Dag containting the arguments of the op. Default to 0 arguments.
   dag arguments = (ins);
diff --git a/mlir/tools/mlir-tblgen/OpDocGen.cpp b/mlir/tools/mlir-tblgen/OpDocGen.cpp
index 7469bfe0ac61..7dbe860d0015 100644
--- a/mlir/tools/mlir-tblgen/OpDocGen.cpp
+++ b/mlir/tools/mlir-tblgen/OpDocGen.cpp
@@ -34,11 +34,12 @@ using namespace mlir;
 
 using mlir::tblgen::Operator;
 
-// Emit the description by first aligning the text to the left per line (e.g.,
-// removing the minimum indentation across the block) and then indenting by 4.
-// This follows from the expectation 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 in the op definition.
+// 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 in the op definition.
 static void emitDescription(StringRef description, raw_ostream &os) {
   // Determine the minimum number of spaces in a line.
   size_t min_indent = -1;
@@ -68,7 +69,7 @@ static void emitDescription(StringRef description, raw_ostream &os) {
       if (printed)
         os << "\n";
     } else {
-      os.indent(4) << split.first.substr(min_indent) << "\n";
+      os << split.first.substr(min_indent) << "\n";
       printed = true;
     }
     remaining = split.second;
@@ -90,8 +91,8 @@ static void emitOpDoc(const RecordKeeper &recordKeeper, raw_ostream &os) {
 
     // Emit summary & description of operator.
     if (op.hasSummary())
-      os << "\n" << op.getSummary();
-    os << "\n";
+      os << "\n" << op.getSummary() << "\n";
+    os << "\n### Description:\n";
     if (op.hasDescription())
       emitDescription(op.getDescription(), os);
 
@@ -101,7 +102,7 @@ static void emitOpDoc(const RecordKeeper &recordKeeper, raw_ostream &os) {
     for (auto operand : op.getOperands()) {
       os << "1. ";
       if (operand.name && !operand.name->getValue().empty())
-        os << operand.name->getAsUnquotedString() << ": ";
+        os << "`" << operand.name->getAsUnquotedString() << "`: ";
       else
         os << "&laquo;unnamed&raquo;: ";
       os << operand.defInit->getAsUnquotedString();
@@ -113,13 +114,27 @@ static void emitOpDoc(const RecordKeeper &recordKeeper, raw_ostream &os) {
     // info. This should be improved.
     os << "\n### Attributes:\n";
     for (auto namedAttr : op.getAttributes()) {
-      os << "- " << namedAttr.getName() << ": ";
+      os << "- `" << namedAttr.getName() << "`: ";
       if (namedAttr.attr.isDerivedAttr())
         os << "derived";
       else
         os << namedAttr.attr.getTableGenDefName();
       os << "\n";
     }
+
+    // Emit results.
+    os << "\n### Results:\n";
+    for (unsigned i = 0, e = op.getNumResults(); i < e; ++i) {
+      os << "1. ";
+      auto name = op.getResultName(i);
+      if (name.empty())
+        os << "&laquo;unnamed&raquo;: ";
+      else
+        os << "`" << name << "`: ";
+      os << op.getResultType(i).getTableGenDefName();
+      os << "\n";
+    }
+
     os << "\n";
   }
 }