Document the v4+ .ForEach() and .Where() methods ("collection operators") #2307
Description
Follow-up from a discussion with @BrucePay
at PowerShell/PowerShell#6576.
The effectively undocumented .Where() and .ForEach methods - available on any object exposed by PowerShell - were introduced in the context of DSC in v4 and provide functionality similar to the Where-Object and ForEach-Object cmdlets, but (a) in a more performant way (albeit in an all-in-memory manner) and (b) with more features.
The most comprehensive documentation that I'm aware of is this third-party blog post by @KirkMunro.
- These methods need to be documented as part of the regular user documentation,
- with the DSC documentation referring to it.
I suggest doing so in the context of the ForEach-Object and Where-Object cmdlets to introduce them as in-memory, expression-mode, preexisting-collection operator-like alternatives to these cmdlets.
Side note: Making these methods bona fide operators is the subject of this RFC.
The inadequate existing references to these methods ("operators"):
Regular documentation:
Starting in Windows PowerShell 4.0, Where() operator behavior has changed. ...
Note only is .Where() not documented itself, the whole paragraph is confusing, because .Where() didn't even exist prior to v4.
"Beginning in PowerShell 4.0, collection filtering by using a method syntax is supported."
DSC documentation:
- Using configuration data in DSC
makes isolated, passing references to.Where()and.ForEach().
* Separating configuration and environment data contains examples (only) of .Where() use.
- (don't know where the sources for these documents are).
Version(s) of document impacted
- Impacts 6.1 document
- Impacts 6.0 document
- Impacts 5.1 document
- Impacts 5.0 document
- Impacts 4.0 document
- Impacts 3.0 document
Reason(s) for not selecting all version of documents
- The documented feature was introduced in selected version of PowerShell