[mlir][quant] Move comments to TableGen statements

[rikhuijzer]

Summary

The quant dialect documentation currently mostly empty (https://mlir.llvm.org/docs/Dialects/QuantDialect/).
This patch moves the comments to TableGen statements.
By looking at the generated QuantDialect.md, I've confirmed that each change in this patch will end up in the documentation.

The only thing that I wasn't able to document was the UniformQuantizedType.
I haven't found a way to document a DialectType since most appear to be private in other dialects; suggestions are welcome.

[jpienaar]

DialectType is a constraint - I think we may want to convert these to be TypeDef and then can have longer definitions - but even before that the doc generator could be improved.

mlir/include/mlir/Dialect/Quant/QuantOps.td

32

Nit: Convert and end with period.

(same below, capital start with period end https://mlir.llvm.org/docs/DefiningDialects/Operations/#operation-documentation )

[rikhuijzer]

In D151649#4379282, @jpienaar wrote:

DialectType is a constraint - I think we may want to convert these to be TypeDef and then can have longer definitions - but even before that the doc generator could be improved.

Thank you for taking a look! I'm unsure what you mean by the last part of your sentence. Do you advice to improve the doc generator as part of this patch or is it more of a statement for the future combined with a doc generator improvement?

mlir/include/mlir/Dialect/Quant/QuantOps.td

32

After looking at the sentence "It should be a one-liner without trailing punctuation.", your comment, and the output of rg 'let summary = ' mlir/, I'm very confused. I see capitalization, trailing punctuation, and no-capitalization in mlir/. Let's ignore for now

[rikhuijzer]

On second thought, probably the idea is to automatically capitalize the sentence and add a dot during documentation generation. Maybe also italicize. That would improve documentation readability. Let me know if this is what you meant and I'll try to make a patch

[mehdi_amini]

Thanks for the doc improvements! Always welcome :)

I'll let Jacques handle the final approval on this :)

[rikhuijzer]

@jpienaar, anything I can do to move this patch forward?

[jpienaar]

In D151649#4379309, @rikhuijzer wrote:

On second thought, probably the idea is to automatically capitalize the sentence and add a dot during documentation generation. Maybe also italicize. That would improve documentation readability. Let me know if this is what you meant and I'll try to make a patch

Indeed that would be nice (even if you look at the TOC being generated ... it could be improved).

In D151649#4395512, @rikhuijzer wrote:

@jpienaar, anything I can do to move this patch forward?

Looks good, let me know if you need help in landing.

mlir/include/mlir/Dialect/Quant/QuantOps.td

32

There is a style convention which is unfortunately inconsistently followed - we could even have the doc generator have a lint mode to catch these, which would be a nice addition too. And of course if it turns out that that style convention needs to be updated, we could do that too.

[rikhuijzer]

Thanks for the reviews, Jacques! I appreciate it.

Indeed that would be nice (even if you look at the TOC being generated ... it could be improved).

It's on my task list and I'll pick it up soon.

Looks good, let me know if you need help in landing.

Yes. :) Could you land this patch and D152123?

mlir/include/mlir/Dialect/Quant/QuantOps.td

 //===----------------------------------------------------------------------===//
 
 class quant_Op<string mnemonic, list<Trait> traits> :
     Op<Quantization_Dialect, mnemonic, traits>;
 
 //===----------------------------------------------------------------------===//
 // Quantization casts
 //===----------------------------------------------------------------------===//
-// A QuantizeCast (qcast) represents a potential type shift from a quantizable
-// type to a quantized type.
-//
-// At runtime, a qcast will apply the transformation expressed by its
-// operand and result type. For flexibility during transformation, it is also
-// possible to have a qcast that performs no transformation (both its
-// operand and result type are quantizable).
-//
-// A qcast will typically originate from either:
-//   a) An expressed or implied constraint in the source dialect which signals
-//      that a certain level of quantization is possible or required.
-//   b) An inference made by a quantization algorithm indicating that a
-//      quantized representation may be acceptable.
-//
-// Especially early in transformation, it is common to have pairs of
-// qcast/dcast at points where a transition to a quantized type is
-// required. In addition, it is also common to have an identity qcast
-// (where the operand and result type are not quantized) at all points where
-// it is legal to use a quantized representation (but is not known to be
-// acceptable).
+
 def quant_QuantizeCastOp : quant_Op<"qcast", [Pure]> {
+  let summary = "convert a quantizable type to a quantized type";
+  let description = [{
+    A QuantizeCast `qcast` represents a potential type shift from a quantizable
+    type to a quantized type.
+
+    At runtime, a `qcast` will apply the transformation expressed by its
+    operand and result type. For flexibility during transformation, it is also
+    possible to have a `qcast` that performs no transformation (both its
+    operand and result type are quantizable).
+
+    A `qcast` will typically originate from either:
+      a) An expressed or implied constraint in the source dialect which signals
+         that a certain level of quantization is possible or required.
+      b) An inference made by a quantization algorithm indicating that a
+         quantized representation may be acceptable.
+
+    Especially early in transformation, it is common to have pairs of
+    `qcast` and `dcast` at points where a transition to a quantized type is
+    required. In addition, it is also common to have an identity `qcast`
+    (where the operand and result type are not quantized) at all points where
+    it is legal to use a quantized representation (but is not known to be
+    acceptable).
+  }];
   let arguments = (ins quant_RealValueType:$arg);
-  let results = (outs quant_RealValueType);
+  let results = (outs quant_RealValueType:$res);
 }
 
-// A DequantizeCast op (dcast) represents the inverse of a qcast,
-// converting back from a quantized to quantizable (expressed) type.
-//
-// Like qcasts, a dcast is allowed to have both its operand and result
-// as non quantized types. This facilitates transformations and marks edges
-// where the computation must be carried out in the expressed type.
-//
-// Especially early in transformation, it is common to have dcasts on
-// all operands to ops that must operate with the expressed type (typically
-// math ops prior to lowering to target-specific, quantized kernels).
 def quant_DequantizeCastOp : quant_Op<"dcast", [Pure]> {
+  let summary = "convert back from a quantized to quantizable (expressed) type operation";
+  let description = [{
+    A DequantizeCast op `dcast` represents the inverse of a `qcast`,
+    converting back from a quantized to quantizable (expressed) type.
+
+    Like `qcast`s, a `dcast` is allowed to have both its operand and result
+    as non quantized types. This facilitates transformations and marks edges
+    where the computation must be carried out in the expressed type.
+
+    Especially early in transformation, it is common to have `dcast`s on
+    all operands to ops that must operate with the expressed type (typically
+    math ops prior to lowering to target-specific, quantized kernels).
+  }];
   let arguments = (ins quant_RealValueType:$arg);
-  let results = (outs quant_RealValueType);
+  let results = (outs quant_RealValueType:$res);
 }
 
-// A StorageCast (scast) represents a cast from or to a type based on the
-// storage type and a type based on a corresponding quantized type.
-//
-// This op exists to ensure type coherency for between parts of the computation
-// which are operating directly on an underlying storage type and those which
-// operate on quantized values.
-//
-// Examples from storage to quantized type:
-//   i8 -> !quant<"uniform[i8:f32]{1.0}">
-//   tensor<4xi8> -> tensor<4x!quant<"uniform[i8:f32]{1.0}">>
-//   vector<4xi8> -> vector<4x!quant<"uniform[i8:f32]{1.0}">>
 def quant_StorageCastOp : quant_Op<"scast", [Pure]> {
+  let summary = "cast from or to a type based on the storage type and the corresponding quantized type";
+  let description = [{
+    A StorageCast `scast` represents a cast from or to a type based on the
+    storage type and a type based on a corresponding quantized type.
+
+    This op exists to ensure type coherency for between parts of the computation
+    which are operating directly on an underlying storage type and those which
+    operate on quantized values.
+
+    Examples from storage to quantized type:
+    ```
+    i8 -> !quant<"uniform[i8:f32]{1.0}">
+    ```
+    ```
+    tensor<4xi8> -> tensor<4x!quant<"uniform[i8:f32]{1.0}">>
+    ```
+    ```
+    vector<4xi8> -> vector<4x!quant<"uniform[i8:f32]{1.0}">>
+    ```
+  }];
   let arguments = (ins quant_RealOrStorageValueType:$arg);
-  let results = (outs quant_RealOrStorageValueType);
+  let results = (outs quant_RealOrStorageValueType:$res);
   let hasFolder = 1;
 }
 
 #endif // DIALECT_QUANT_QUANT_OPS_

mlir/include/mlir/Dialect/Quant/QuantOpsBase.td

def quant_RealValueType :
     quant_TypedPrimitiveOrContainer<quant_RealPrimitiveType>;
 
 // A primitive or container of StoragePrimitiveType.
 def quant_StorageValueType :
     quant_TypedPrimitiveOrContainer<quant_StoragePrimitiveType>;
 
 // Either a real valued or storage primitive or container type.
 def quant_RealOrStorageValueType :
-    Type<Or<[quant_RealValueType.predicate,
-                quant_StorageValueType.predicate]>>;
+    Type<Or<[quant_RealValueType.predicate, quant_StorageValueType.predicate]>,
+    "real valued or storage primitive or container type">;
 
 // An implementation of UniformQuantizedType.
 def quant_UniformQuantizedType :
     DialectType<Quantization_Dialect,
                 CPred<"::llvm::isa<UniformQuantizedType>($_self)">,
                 "UniformQuantizedType">;
 
 // Predicate for detecting a container or primitive of UniformQuantizedType.
 def quant_UniformQuantizedValueType :
     quant_TypedPrimitiveOrContainer<quant_UniformQuantizedType>;
 
 #endif // DIALECT_QUANT_QUANT_OPS_BASE_