[flang-commits] [flang] [flang][docs] Add note about Cray pointers and the TARGET attribute (PR #137993)

[Eugene Epshteyn via flang-commits]

================
@@ -264,11 +264,30 @@ Fortran also has no rule against associating read-only data with a pointer.
 Cray pointers are, or were, an extension that attempted to provide
 some of the capabilities of modern pointers and allocatables before those
 features were standardized.
-They had some aliasing restrictions; in particular, Cray pointers were
-not allowed to alias each other.
 
-They are now more or less obsolete and we have no plan in place to
-support them.
+They had some aliasing restrictions; in particular, Cray pointers were not
+allowed to alias each other.
+
+In this example, `handle` aliases with `target`.
+
+```
+integer(kind=8) :: target(10)
+integer(kind=8) :: ptr
+integer(kind=8) :: handle(10)
+pointer(ptr, handle)
+target = 1
+ptr = loc(target)
+print *, target
+end
+```
+
+Optimizations assume that Cray pointers do not alias any other variables.
+In the above example, it is assumed that `handle` and `target` do not alias,
+and optimizations will treat them as seperate entities.
+
+You may add the TARGET attribute to variables aliasing with a Cray pointer (the
+`target` variable in this example), and this will disable some optimizations
+that would otherwise assume there is no aliasing.
----------------
eugeneepshteyn wrote:

I wonder, if this should be more strongly worded, because without `target` attribute the optimizations are very likely to produce bad code. For example: 

"... and optimizations will treat them as separate entities and produce incorrect code.

In order to disable optimizations that assume that there's no aliasing, add TARGET attribute to variables aliasing with a Cray pointer (the `target` variable in this example)."

https://github.com/llvm/llvm-project/pull/137993