[mlir][acc][nfc] Update type interface descriptions (#147807)

PointerLikeType and MappableType interfaces are now described with more
detail.

Author: razvanlupusoru

mlir/include/mlir/Dialect/OpenACC/OpenACCTypeInterfaces.td

@@ -15,7 +15,27 @@ def OpenACC_PointerLikeTypeInterface : TypeInterface<"PointerLikeType"> {
   let cppNamespace = "::mlir::acc";
 
   let description = [{
-    An interface for pointer-like types that point to an OpenACC var.
+    This is a minimal interface to interact with acc dialect data clause
+    operations to represent an OpenACC variable. The reason for its existence
+    is to create a minimal contract between a source dialect and the acc
+    dialect - and it works on the basis that this is a pointer that can
+    be mapped to device memory. This exists for the following reasons:
+    - Many dialects choose to represent their variables as pointers.
+      Specifically locals are created with some form of `alloca` and globals
+      are referred through by their address.
+    - Eventually all such pointers end up as LLVM pointers along with LLVM
+      types whose size is computable. This is the minimal information needed
+      to map a variable.
+    - The OpenACC spec describes reference counters in terms of memory
+      addressability. In 2.6.7. It says: "A structured reference counter
+      is incremented when entering each data or compute region that contain
+      an explicit data clause or implicitly-determined data attributes for
+      that section of memory". This implies addressability of memory.
+    - Attach semantics (2.6.8 attachment counter) are specified using
+      "address" terminology: "The attachment counter for a pointer is set to
+      one whenever the pointer is attached to new target address, and
+      incremented whenever an attach action for that pointer is performed for
+      the same target address."
   }];
 
   // By convention, any of the pointer types associated with this interface
@@ -57,8 +77,13 @@ def OpenACC_MappableTypeInterface : TypeInterface<"MappableType"> {
   let cppNamespace = "::mlir::acc";
 
   let description = [{
-    An interface to capture type-based semantics for mapping in a manner that
-    makes it convertible to size-based semantics.
+    This interface is a richer contract than being a pointer-like type
+    and can be used in conjunction with it.
+    It should be attached to types that a source dialect considers to
+    be variables. And unlike pointer-like type, it can be attached to variables
+    which the source dialect does not represent through the use of memory.
+    The richer API allows for post-frontend type-based semantics to be
+    applied such as generating recipes or extracting array bounds.
   }];
 
   let methods = [