Add notes to 'release/examples' about ref intents (chapel-lang#23505)

Adds comments about forall loops requiring ref intents. This does not
add a comment at every place, just where the loop structure is called
out.

Note that the "Task Intents Inside Record Methods" section in
`test/release/examples/primers/forallLoops.chpl` needs to be updated,
but that requires both a test code change and bug fix, which will happen
post-release

[Reviewed by @vasslitvinov]

test/release/examples/benchmarks/hpcc/ra-atomics.chpl

@@ -104,7 +104,7 @@ proc main() {
   //
   // In parallel, initialize the table such that each position
   // contains its index.  "[i in TableSpace]" is shorthand for "forall
-  // i in TableSpace"
+  // i in TableSpace".  "with (ref T)" is required since we are modifying "T".
   //
   [i in TableSpace with (ref T)] T(i).poke(i);
 

test/release/examples/benchmarks/hpcc/ra.chpl

@@ -128,7 +128,7 @@ proc main() {
   //
   // In parallel, initialize the table such that each position
   // contains its index.  "[i in TableSpace]" is shorthand for "forall
-  // i in TableSpace"
+  // i in TableSpace".  "with (ref T)" is required since we are modifying "T".
   //
   [i in TableSpace with (ref T)] T[i] = i;
 

test/release/examples/benchmarks/hpcc/variants/ra-cleanloop.chpl

@@ -124,7 +124,7 @@ proc main() {
   //
   // In parallel, initialize the table such that each position
   // contains its index.  "[i in TableSpace]" is shorthand for "forall
-  // i in TableSpace"
+  // i in TableSpace".  "with (ref T)" is required since we are modifying "T".
   //
   [i in TableSpace with (ref T)] T[i] = i;
 

test/release/examples/benchmarks/hpcc/variants/ra-unordered-atomics.chpl

@@ -91,7 +91,7 @@ proc main() {
   //
   // In parallel, initialize the table such that each position
   // contains its index.  "[i in TableSpace]" is shorthand for "forall
-  // i in TableSpace"
+  // i in TableSpace".  "with (ref T)" is required since we are modifying "T".
   //
   [i in TableSpace with (ref T)] T(i).poke(i);
 

test/release/examples/primers/arrays.chpl

@@ -128,7 +128,11 @@ writeln("After incrementing B's elements, B is:\n", B, "\n");
 // from the ranges specified within the array type's square brackets.
 // Array ``A2`` above will have the implicit domain ``{0..4}`` to
 // represent the five values in its initializing expression.
-
+//
+// The explicit ``ref`` intent is required for ``B`` in the example below
+// because ``B`` is not modifed directly through the loop's index variable (in
+// this case ``i`` and ``j``).
+//
 // An array's domain can be queried using the ``.domain`` method,
 // which returns a ``const ref`` to the domain in question.  For
 // example, here's a loop that iterates over B's indices in parallel
@@ -158,7 +162,7 @@ proc negateAndPrintArr(ref X: [?D] real) {
 negateAndPrintArr(B);
 
 //
-// Arrays are passed to routines by constant reference (``const ref``) by
+// Arrays are passed to routines by constant (``const``) by
 // default, which does not allow them to be modified within the routine.
 // The above procedure ``negateAndPrintArr()`` must use a non-constant
 // reference intent (``ref``) explicitly, so that its modifications of ``X``

test/release/examples/primers/forallLoops.chpl

@@ -32,8 +32,9 @@ an expression. Both kinds are shown in the following sections.
 "Must-parallel" forall statement
 --------------------------------
 
-In the following example, the forall loop iterates over the array indices
-in parallel:
+In the following example, the forall loop iterates over the array indices in
+parallel. Since the loop iterates over ``1..n`` and not ``A``, an explicit
+``ref`` intent must be used to allow modification of ``A``.
 */
 
 config const n = 5;
@@ -81,7 +82,8 @@ provide a "leader" iterator and all iterables provide "follower" iterators.
 These are described in the :ref:`parallel iterators primer
 <primers-parIters-leader-follower>`.
 
-Here we illustrate zippering arrays and domains:
+Here we illustrate zippering arrays and domains. In this example, we must
+explicitly mark ``C`` as modified with a ``ref`` intent.
 */
 
 var C: [1..n] real;
@@ -187,7 +189,8 @@ of shadow variables, one per outer variable.
 The default argument intent (:ref:`The_Default_Intent`) is used by default.
 For numeric types, this implies capturing the value of the outer
 variable by the time the task starts executing. Arrays are passed by
-reference, as are sync and atomic variables
+constant reference, so to modify them we must use an explicit intent.
+Sync and atomic variables are passed by reference
 (:ref:`primers-syncs`, :ref:`primers-atomics`).
 */
 

test/studies/hpcc/FFT/fft.chpl

@@ -205,7 +205,7 @@ proc dfft(ref A: [?ADom], W, cyclicPhase) {
 
 //
 // this is the radix-4 butterfly routine that takes multipliers wk1,
-// wk2, and wk3 and a 4-element array (slice) A.
+// wk2, and wk3 and a 4-element array (slice) X.
 //
 proc butterfly(wk1, wk2, wk3, ref X:[?D]) {
   const i0 = D.low,

test/studies/hpcc/HPL/hpl.chpl

@@ -170,7 +170,7 @@ proc LUFactorize(n: int, ref Ab: [?AbD] elemType,
 //     |aaaaa|.....|.....|.....|  function but called AD here.  Similarly,
 //     +-----+-----+-----+-----+  'b' was 'tr' in the calling code, but BD
 //     |aaaaa|.....|.....|.....|  here.
-//     |aaaaa|.....|.....|.....|  
+//     |aaaaa|.....|.....|.....|
 //     |aaaaa|.....|.....|.....|
 //     +-----+-----+-----+-----+
 //

test/studies/hpcc/RA/diten/ra.chpl

@@ -100,7 +100,7 @@ proc main() {
   //
   // In parallel, initialize the table such that each position
   // contains its index.  "[i in TableSpace]" is shorthand for "forall
-  // i in TableSpace"
+  // i in TableSpace".  "with (ref T)" is required since we are modifying "T".
   //
   [i in TableSpace with (ref T)] T(i) = i;
   for loc in Locales {