New Issue: Improve / formalize 'foreach' documentation

19153, "bradcray", "Improve / formalize 'foreach' documentation", "2022-02-01T17:06:30Z"

Currently, foreach loops are described in a technical note, which is not unusual for a new feature. However, that note is a little vague about when a foreach loop can be applied legally, indicating that it's when the iterations are order-independent. However, a loop like:

var sum: int;
foreach i in 1..n do
  sum += i;

is arguably order-independent, but is not clear that it should be permitted with a foreach loop, similar to how it is not for a forall loop. That suggests that we should be adding shadow variables and supporting task intents, as described in #18500 (whose comments also include a bit more discussion about this case).

I'm filing this issue to capture the notion that we also need to improve the documentation to clarify what foreach loops can or cannot contain so that people aren't writing code that is intended to be illegal.