Need additional documentation on how the instrinsic ForEach method wraps results in a collection

[rkeithhill]

Prerequisites

• Existing Issue: Search the existing issues for this repository. If there is an issue that fits your needs do not file a new one. Subscribe, react, or comment on that issue instead.
• Descriptive Title: Write the title for this issue as a short synopsis. If possible, provide context. For example, "Typo in Get-Foo cmdlet" instead of "Typo."
• Verify Version: If there is a mismatch between documentation and the behavior on your system, ensure that the version you are using is the same as the documentation. Check this box if they match or the issue you are reporting is not version specific.

Links

https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_arrays?view=powershell-7.5#foreachstring-propertyname

Summary

There is no information on the .ForEach(string propertyName) form that discusses how PowerShell handles properties that are collections. This issue has been raised in the PowerShell repo and the Engine-WG looked at this and concluded we need more documentation for the semantics of .ForEach(propName)

Details

Note how .ForEach() wraps both the scalar property and the array property within a collection such that accessing the first element of the original collection requires two indices [0][0]. The first index is for the wrapper collection that PowerShell creates, and then the second index is for the first element in the array returned by the referenced property name.

Suggested Fix

Update the topic to cover these semantics of ForEach(string propertyName).