[Docs] Make op/attr/type summary styles consistent (#20726)

We have been publishing dialect docs for some time and the summary
fields across our dialects were inconsistently styled. This changes all
summaries to read more like a sentence (capitalized w/ punctuation) and
cleans up a few summaries/descriptions. Switches to use braces
everywhere as they make multi-line descriptions easier.

- flow.reshape/bitcast descriptions are improved
- iree_codegen.query_tile_sizes description is improved
- util.global.load description and summary are slightly less redundant

There is still a lot of room for improvement on the contents of the
docs, but this is a good first step.

---------

Co-authored-by: Han-Chung Wang <[email protected]>

Author: qedawkins

compiler/src/iree/compiler/Codegen/Common/TransformExtensions/CommonExtensionsOps.td

@@ -179,7 +179,7 @@ def CopyTensorOperandOp :  Op<Transform_Dialect, "iree.copy_tensor_operand",
      TransformEachOpTrait,
      TransformOpInterface,
      ReportTrackingListenerFailuresOpTrait]> {
-  let summary = "Hoist static allocations";
+  let summary = [{Create a linalg copy of a specified value.}];
   let description = [{
     Inserts a copy of the specified operand of the target operation.
 
@@ -214,7 +214,7 @@ def GpuDistributeSharedMemoryCopyOp :
   Op<Transform_Dialect, "iree.gpu_distribute_shared_memory_copy",
     [DeclareOpInterfaceMethods<MemoryEffectsOpInterface>,
      TransformOpInterface, TransformEachOpTrait]> {
-  let summary = "Distribute shared memory copies";
+  let summary = [{Distribute shared memory copies.}];
   let description = [{
     Find copies to/from shared memory and distribute the copies based on the
     workgroup size.
@@ -244,7 +244,7 @@ def HoistStaticAllocOp :  Op<Transform_Dialect, "iree.hoist_static_alloc",
      TransformEachOpTrait,
      TransformOpInterface,
      ReportTrackingListenerFailuresOpTrait]> {
-  let summary = "Hoist static allocations";
+  let summary = [{Hoist static allocations.}];
   let description = [{
     Find static allocations and hoist them to the top level.
 
@@ -470,8 +470,9 @@ def MatchHasNoLoweringConfigOp : Op<Transform_Dialect, "iree.match.has_no_loweri
     [MatchOpInterface,
      SingleOpMatcher,
      MemoryEffectsOpInterface]> {
-  let summary =
-      "Checks that the payload op does not carry a lowering config or compilation info";
+  let summary = [{
+    Checks that the payload op does not carry a lowering config or compilation info.
+  }];
   let description = [{
     Verifies that the payload does not have a "compilation_info" or
     "lowering_config" attribute. This is a very common check needed for external
@@ -530,7 +531,7 @@ def ReduceSharedMemoryBankConflictsOp :  Op<Transform_Dialect, "iree.reduce_shar
      TransformEachOpTrait,
      TransformOpInterface,
      ReportTrackingListenerFailuresOpTrait]> {
-  let summary = "Add padding to 'memref.alloc' ops reduce shared memory bank conflicts";
+  let summary = [{Add padding to 'memref.alloc' ops reduce shared memory bank conflicts.}];
   let description = [{
     The `paddingSizeBits` argument should be picked based on the target
     architecture, striking balance between minimizing bank conflicts and keeping

compiler/src/iree/compiler/Codegen/Dialect/CPU/IR/IREECPUAttrs.td

@@ -18,7 +18,7 @@ include "mlir/IR/AttrTypeBase.td"
 def IREECPU_CPUEncodingLayoutAttr :
     AttrDef<IREECPU_Dialect, "CPUEncodingLayout"> {
   let mnemonic = "cpu_encoding_layout";
-  let summary = "The encoding layout attribute for CPU backends.";
+  let summary = [{The encoding layout attribute for CPU backends.}];
   let description = [{
     This attribute can implement any layout interface methods for data-tiling,
     e.g., Codegen::LayoutAttrInterface, etc. They are implemented through
@@ -37,7 +37,7 @@ def IREECPU_CPUEncodingLayoutAttr :
 def IREECPU_VMVXEncodingLayoutAttr :
     AttrDef<IREECPU_Dialect, "VMVXEncodingLayout"> {
   let mnemonic = "vmvx_encoding_layout";
-  let summary = "The encoding layout attribute for VMVX backend.";
+  let summary = [{The encoding layout attribute for VMVX backend.}];
   let description = [{
     This attribute can implement any layout interface methods for data-tiling,
     e.g., Codegen::LayoutAttrInterface, etc. They are implemented through

compiler/src/iree/compiler/Codegen/Dialect/Codegen/IR/IREECodegenAttrs.td

@@ -204,7 +204,7 @@ def WorkgroupMappingAttr :
 def IREECodegen_TranslationInfoAttr :
     AttrDef<IREECodegen_Dialect, "TranslationInfo", []> {
   let mnemonic = "translation_info";
-  let summary = [{drive dispatch entry point lowering}];
+  let summary = [{Drive dispatch entry point lowering.}];
   let description = [{
     Specifies the information that is used to drive the translation of
     an entry point function using Linalg based structured-op
@@ -294,7 +294,7 @@ def IREECodegen_LoweringConfigAttr :
       ]>
     ]> {
   let mnemonic = "lowering_config";
-  let summary = [{drive lowering of an operation within dispatch region}];
+  let summary = [{Drive lowering of an operation within dispatch region.}];
   let description = [{
     Default implementation of a lowering configuration attribute. It includes
     only tiling and optionally vectorization information. The interpretation of
@@ -364,7 +364,7 @@ def IREECodegen_LoweringConfigAttr :
 def IREECodegen_CompilationInfoAttr :
     AttrDef<IREECodegen_Dialect, "CompilationInfo", []> {
   let mnemonic = "compilation_info";
-  let summary = [{drive lowering of an operation from input dialect}];
+  let summary = [{Drive lowering of an operation from input dialect.}];
   let description = [{
     Specifies the information that allows controlling the compilation
     of operations like `linalg.matmul`/`linalg.*conv` within
@@ -398,7 +398,7 @@ def IREECodegen_CompilationInfoAttr :
 
 def IREECodegen_ExportConfig : AttrDef<IREECodegen_Dialect, "ExportConfig", []> {
   let mnemonic = "export_config";
-  let summary = "User defined workgroup size specification";
+  let summary = [{User defined workgroup size specification.}];
   let description = [{
     Allows setting workgroup size for pre-formed dispatches.
   }];
@@ -426,7 +426,7 @@ def IREECodegen_EncodingNopLayoutAttr  :
       ]>
     ]> {
   let mnemonic = "encoding_nop_layout";
-  let summary = "An attribute with implementation that treats encoding as nop.";
+  let summary = [{An attribute with implementation that treats encoding as nop.}];
   let description = [{
     An attribute that implements the interface methods that discards the
     encodings. It can be a default attribute when a backend does not implement
@@ -446,7 +446,7 @@ def IREECodegen_RotateRowsAttr  :
       ]>
     ]> {
   let mnemonic = "rotate_rows";
-  let summary = "An attribute that describes a swizzling pattern for rotating rows.";
+  let summary = [{An attribute that describes a swizzling pattern for rotating rows.}];
   let description = [{
     This attribute rotates accesses of |access_width| within rows of size
     |row_width|. For any given access into logical memref of shape

compiler/src/iree/compiler/Codegen/Dialect/Codegen/IR/IREECodegenOps.td

@@ -20,10 +20,12 @@ def TensorTypeAttr : TypeAttrBase<"TensorType", "Tensor type attribute">;
 
 def IREECodegen_QueryTileSizesOp :
     Op<IREECodegen_Dialect, "query_tile_sizes", [Pure]> {
-  let summary = "Query tile sizes";
+  let summary = [{Yields tile sizes for the specified tensor type.}];
 
   let description = [{
-    Query tile sizes
+    For targets where tile sizes can't be resolved at compile time, this
+    operation allows querying the sizes at runtime. Today this only applies
+    to VMVX.
   }];
 
   let arguments = (ins TensorTypeAttr:$tensor_type);
@@ -43,7 +45,7 @@ def IREECodegen_ExtractStridedMetadataOp : Op<IREECodegen_Dialect, "extract_stri
     SameVariadicResultSize,
     ViewLikeOpInterface,
     InferTypeOpAdaptor]> {
-  let summary = "Extracts a buffer base with offset and strides";
+  let summary = [{Extracts a buffer base with offset and strides.}];
   let description = [{
     This op is implemented similarly to the upstream MemRef::ExtractStridedMetadataOp
     with the following differences.
@@ -109,7 +111,7 @@ def IREECodegen_ExtractStridedMetadataOp : Op<IREECodegen_Dialect, "extract_stri
 
 def IREECodegen_SwizzleHintOp : Op<IREECodegen_Dialect, "swizzle_hint", [
     SameOperandsAndResultType, Pure]> {
-  let summary = "Hint to swizzle accesses according to an access pattern";
+  let summary = [{Hint to swizzle accesses according to an access pattern.}];
   let description = [{
     Optimization hint to swizzle all accesses to the memref this takes a view
     of. This only affects reads/writes immediately consuming this operation and
@@ -163,7 +165,7 @@ def IREECodegen_SwizzleHintOp : Op<IREECodegen_Dialect, "swizzle_hint", [
 
 def IREECodegen_NullPointerOp :
      Op<IREECodegen_Dialect, "null_pointer", [Pure]> {
-  let summary = "Returns a null_pointer value.";
+  let summary = [{Returns a null_pointer value.}];
   let description = [{
     This is meant to be used only as arguments to microkernels.
   }];
@@ -177,7 +179,7 @@ def IREECodegen_NullPointerOp :
 
 def IREECodegen_LoadFromMemrefOp : Op<IREECodegen_Dialect, "load_from_memref",
     [DeclareOpInterfaceMethods<MemoryEffectsOpInterface>]> {
-  let summary = [{loads a tensor from a memref}];
+  let summary = [{Loads a tensor from a memref.}];
   let description = [{
     Loads a tensor from a memref with a compatible shape and the same element
     type.
@@ -199,7 +201,7 @@ def IREECodegen_LoadFromMemrefOp : Op<IREECodegen_Dialect, "load_from_memref",
 
 def IREECodegen_StoreToMemrefOp : Op<IREECodegen_Dialect, "store_to_memref",
     [DeclareOpInterfaceMethods<MemoryEffectsOpInterface>]> {
-  let summary = [{stores a tensor into a memref}];
+  let summary = [{Stores a tensor into a memref.}];
   let description = [{
     Stores a tensor into a memref with a compatible shape and the same element
     type.

compiler/src/iree/compiler/Codegen/Dialect/Codegen/IR/IREECodegenTypes.td

@@ -11,7 +11,7 @@ include "iree/compiler/Codegen/Dialect/Codegen/IR/IREECodegenDialect.td"
 
 def NullPointer
   : TypeDef<IREECodegen_Dialect, "NullPointer", []> {
-  let summary = "Pseudo null-pointer type. Lowers to a null pointer.";
+  let summary = [{Pseudo null-pointer type. Lowers to a null pointer.}];
   let description = [{
     This is meant to be used only as arguments to microkernels.
   }];

compiler/src/iree/compiler/Codegen/Dialect/Codegen/IR/UKernelOps.td

@@ -22,7 +22,7 @@ class IREECodegen_UKernelOp<string mnemonic, list<Trait> traits = []> :
 def IREECodegen_UKernelGenericOp :
     IREECodegen_UKernelOp<"ukernel.generic", [
       AttrSizedOperandSegments]> {
-  let summary = "Generic Microkernel operator";
+  let summary = [{Generic Microkernel operator.}];
 
   let description = [{
     Operation to wrap a computation forwarded to a microkernel.

compiler/src/iree/compiler/Codegen/Dialect/GPU/IR/IREEGPUAttrs.td

@@ -44,7 +44,7 @@ def IREEGPU_LoweringConfigAttr :
       ]>
     ]> {
   let mnemonic = "lowering_config";
-  let summary = "drive lowering of an operation for gpu compilation.";
+  let summary = [{Drive lowering of an operation for gpu compilation.}];
   let description = [{
     GPU specific implementation of a lowering config. This carries just a
     dictionary attribute to store any relevant fields. This is the simplest
@@ -69,7 +69,7 @@ def IREEGPU_DerivedThreadConfig :
     ]> {
   let mnemonic = "derived_thread_config";
   let summary = [{
-    drive lowering of an operation by deriving thread distribution when needed.
+    Drive lowering of an operation by deriving thread distribution when needed.
   }];
   let description = [{
     Lowering config for a single thread tiling level that is inferred after
@@ -295,7 +295,7 @@ def IREEGPU_MmaScheduleAttr : AttrDef<IREEGPU_Dialect, "MMASchedule"> {
 def IREEGPU_GPUEncodingLayoutAttr :
     AttrDef<IREEGPU_Dialect, "GPUEncodingLayout"> {
   let mnemonic = "gpu_encoding_layout";
-  let summary = "The encoding layout attribute for GPU backend";
+  let summary = [{The encoding layout attribute for GPU backend.}];
   let description = [{
     This attribute can implement any layout interface methods for data-tiling,
     e.g., Codegen::LayoutAttrInterface, etc. They should be implemented
@@ -319,7 +319,7 @@ def IREEGPU_GPUEncodingLayoutAttr :
 
 def IREEGPU_GPUPadLayoutAttr : AttrDef<IREEGPU_Dialect, "GPUPadLayout"> {
   let mnemonic = "gpu_pad_layout";
-  let summary = "The padded encoding layout attribute for GPU targets.";
+  let summary = [{The padded encoding layout attribute for GPU targets.}];
   let assemblyFormat = "`<` struct(params) `>`";
 
   let description = [{
@@ -345,7 +345,7 @@ def IREEGPU_GPUPadLayoutAttr : AttrDef<IREEGPU_Dialect, "GPUPadLayout"> {
 //===----------------------------------------------------------------------===//
 
 def IREEGPU_TargetWgpAttr : AttrDef<IREEGPU_Dialect, "TargetWgp"> {
-  let summary = "Workgroup processor level target description";
+  let summary = [{Workgroup processor level target description.}];
   let description = [{
     This attribute contains hardware features/limits at a single GPU workgroup
     processor (WGP) level. Here a GPU workgroup processor means the basic
@@ -403,7 +403,7 @@ def IREEGPU_TargetWgpAttr : AttrDef<IREEGPU_Dialect, "TargetWgp"> {
 // AMD compute units or NVIDIA streaming multiprocessors; it's the final SKU.
 
 def IREEGPU_TargetChipAttr : AttrDef<IREEGPU_Dialect, "TargetChip"> {
-  let summary = "Chip level target description";
+  let summary = [{Chip level target description.}];
   let description = [{
     This attribute contains hardware features/limits at a single GPU chip level.
     Here a GPU chip means the hardware functionality scope where the whole
@@ -433,7 +433,7 @@ def IREEGPU_TargetChipAttr : AttrDef<IREEGPU_Dialect, "TargetChip"> {
 //===----------------------------------------------------------------------===//
 
 def IREEGPU_TargetAttr : AttrDef<IREEGPU_Dialect, "Target"> {
-  let summary = "Full GPU target attribute";
+  let summary = [{Full GPU target attribute.}];
   let description = [{
     This attributes describes a full GPU target. It contains a few fields:
     * The canonical target architecture for compilation, e.g., sm_80 for
@@ -530,7 +530,7 @@ def IREEGPU_LaneIdAttr : AttrDef<IREEGPU_Dialect, "LaneId", [
 def IREEGPU_UKernelConfigAttr  :
     AttrDef<IREEGPU_Dialect, "UKernelConfig", []> {
   let mnemonic = "ukernel_config";
-  let summary = "An attribute specifying a ukernel that an op can lower to.";
+  let summary = [{An attribute specifying a ukernel that an op can lower to.}];
   let description = [{
     An attribute that can be applied to any operation to specify that it has
     been matched with a ukernel that is a legal lowering for it.
@@ -554,7 +554,7 @@ def IREEGPU_ReorderWorkgroupsStrategyAttr :
 }
 
 def IREEGPU_GPUPipelineOptionsAttr : AttrDef<IREEGPU_Dialect, "GPUPipelineOptions"> {
-  let summary = "GPU pipeline options attribute.";
+  let summary = [{Options attribute for linalg + tensors -> vector + memref GPU pipelines.}];
   let description = [{
     This attributes describes lowering pipeline specific configuration options:
     * prefetch_shared_memory: Boolean option indicating whether or not to run

compiler/src/iree/compiler/Codegen/Dialect/GPU/IR/IREEGPUOps.td

@@ -26,7 +26,7 @@ def IREEGPU_BarrierRegionOp : Op<IREEGPU_Dialect, "barrier_region", [
     Pure,
     SingleBlockImplicitTerminator<"mlir::iree_compiler::IREE::GPU::YieldOp">
     ]> {
-  let summary = "Synchronizes uses of a shared tensor.";
+  let summary = [{Synchronizes workers on a region of shared code.}];
   let description = [{
     This op is designed to represent synchronization of workers on the operands
     and results of the given region. This operation naturally arises when combining
@@ -125,7 +125,7 @@ def IREEGPU_MultiMmaOp : Op<IREEGPU_Dialect, "multi_mma", [
         "getTiledImplementation",
         "getResultTilePosition"]>
     ]> {
-  let summary = "Models a contraction of multiple mma operations";
+  let summary = [{Models a contraction of multiple mma operations.}];
   let description = [{
     Computes the sum of inner MMA operations along a set of outer dimensions.
     Logically matches closely with a `vector.contraction` operation, however
@@ -391,7 +391,7 @@ def IREEGPU_MultiMmaOp : Op<IREEGPU_Dialect, "multi_mma", [
 def IREEGPU_ValueBarrierOp : Op<IREEGPU_Dialect, "value_barrier", [
   Pure,
   AllTypesMatch<["inputs", "results"]>]> {
-  let summary = "Synchronizes workers on a value semantic tensor or vector.";
+  let summary = [{Synchronizes workers on a value semantic tensor or vector.}];
   let description = [{
     This operation acts as a barrier on a value semantic SSA values (tensor or
     vector). It takes multiple operands and produces a value equivalent to each
@@ -444,7 +444,7 @@ def IREEGPU_ValueBarrierOp : Op<IREEGPU_Dialect, "value_barrier", [
 def IREEGPU_YieldOp : Op<IREEGPU_Dialect, "yield", [
     Pure, ReturnLike, Terminator,
     HasParent<"::mlir::iree_compiler::IREE::GPU::BarrierRegionOp">]> {
-  let summary = "Yield values from a region";
+  let summary = [{Yield values from a iree_gpu region.}];
   let description = [{
      This operation is used to yield values from a within a region.
   }];
@@ -469,7 +469,7 @@ def IREEGPU_YieldOp : Op<IREEGPU_Dialect, "yield", [
 def IREEGPU_BufferResourceCastOp : Op<IREEGPU_Dialect, "buffer_resource_cast", [
   Pure,
   AllTypesMatch<["input", "result"]>]> {
-  let summary = "Represents a cast to addr_space<7> (buffer resource) before bufferization";
+  let summary = [{Represents a cast to addr_space<7> (buffer resource) before bufferization.}];
   let description = [{
     Nominal cast of a tensor to AMDGPU buffer resource memory space before
     bufferization. This op takes the parameters with which to perform the cast

compiler/src/iree/compiler/Codegen/Dialect/VectorExt/IR/VectorExtAttrs.td

@@ -16,7 +16,7 @@ include "iree/compiler/Codegen/Dialect/VectorExt/IR/VectorExtBase.td"
 def NestedLayoutAttr : IREEVectorExt_Attr<"NestedLayout",
       [ DeclareAttrInterfaceMethods<VectorLayoutInterface> ]> {
   let mnemonic = "nested_layout";
-  let summary = [{A layout representing a mapping from GPU thread hierarchy to a shape}];
+  let summary = [{A layout representing a mapping from GPU thread hierarchy to a shape.}];
   let description = [{
     This layout explicitly defines how the shape of the associated vector
     is mapped to a compute hierarchy.

compiler/src/iree/compiler/Codegen/Dialect/VectorExt/IR/VectorExtOps.td

@@ -30,7 +30,7 @@ def IREEVectorExt_ToLayoutOp : IREEVectorExt_PureOp<"to_layout", [
   Pure,
   AllTypesMatch<["input", "output"]>
   ]> {
-  let summary = "Layout conversion operator";
+  let summary = [{Layout conversion operator.}];
   let description = [{
     The layout conversion operator takes a shaped value and a layout and
     transforms the value to have that layout.
@@ -78,7 +78,7 @@ def IREEVectorExt_ToLayoutOp : IREEVectorExt_PureOp<"to_layout", [
 
 def IREEVectorExt_ToSIMDOp : IREEVectorExt_PureOp<"to_simd",
     [SameOperandsAndResultElementType, Pure]> {
-  let summary = "SIMT to SIMD conversion operation";
+  let summary = [{SIMT to SIMD conversion operation.}];
   let description = [{
     This operation is a temporary operation useful for source/target
     materializations when doing type conversions between distributed and not
@@ -97,7 +97,7 @@ def IREEVectorExt_ToSIMDOp : IREEVectorExt_PureOp<"to_simd",
 
 def IREEVectorExt_ToSIMTOp : IREEVectorExt_PureOp<"to_simt",
     [SameOperandsAndResultElementType, Pure]> {
-  let summary = "SIMD to SIMT conversion operation";
+  let summary = [{SIMD to SIMT conversion operation.}];
   let description = [{
     This operation is a temporary operation useful for source/target
     materializations when doing type conversions between distributed and not
@@ -131,7 +131,7 @@ def IREEVectorExt_TransferGatherOp : IREEVectorExt_PureOp<"transfer_gather", [
                        BoolArrayAttr:$in_bounds);
   let results = (outs AnyVectorOfAnyRank:$vector);
 
-  let summary = "Gathers a supervector from memory into an SSA vector value.";
+  let summary = [{Gathers a supervector from memory into an SSA vector value.}];
 
   let description = [{
     The iree_vector_ext.transfer_gather operation provides a structured