Clarify which positional parameters are used in the examples (#11056)

Author: sdwheeler

reference/5.1/Microsoft.PowerShell.Core/About/about_Simplified_Syntax.md

@@ -1,26 +1,24 @@
 ---
 description: Describes easier, more natural-language ways of scripting filters for collections of objects.
 Locale: en-US
-ms.date: 06/09/2017
+ms.date: 04/26/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_simplified_syntax?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about Simplified Syntax
 ---
-
 # about_Simplified_Syntax
 
 ## Short description
-
 Describes easier, more natural-language ways of scripting filters for
 collections of objects.
 
 ## Long description
 
 Simplified syntax, introduced in Windows PowerShell 3.0, lets you build some
-filter commands without using script blocks. The simplified syntax more
-closely resembles natural language, and is primarily useful with collections
-of objects that get piped into commands `Where-Object` and `ForEach-Object` and
-their corresponding aliases `where` and `foreach`.
+filter commands without using script blocks. The simplified syntax more closely
+resembles natural language, and is primarily useful with collections of objects
+that get piped into commands `Where-Object` and `ForEach-Object` or their
+corresponding aliases `where` and `foreach`.
 
 You can use a method on the members of a collection (most commonly, an array)
 without referring to the automatic variable `$_` inside a script block.
@@ -30,41 +28,65 @@ Consider the following two invocations:
 ### Standard Syntax
 
 ```powershell
-dir Cert:\LocalMachine\Root | where { $_.FriendlyName -eq 'Verisign' }
-dir Cert:\ -Recurse | foreach { $_.GetKeyAlgorithm() }
+Get-ChildItem Cert:\LocalMachine\Root |
+    Where-Object -FilterScript { $_.FriendlyName -eq 'Verisign' }
+Get-ChildItem Cert:\ -Recurse |
+    ForEach-Object -FilterScript { $_.GetKeyAlgorithm() }
 ```
 
+> [!NOTE]
+> In the second command, the `GetKeyAlgorithm` method is called on each object
+> in the collection. If the object received from the pipeline doesn't have a
+> `GetKeyAlgorithm` method, the command produces an error.
+
 ### Simplified syntax
 
-Under the simplified syntax, comparison operators that work on members of objects in a
-collection are treated as parameters. You can invoke a method on objects in a
-collection without referring to the automatic variable `$_` inside a script block.
-Compare the following two invocations to those of the previous example:
+Under the simplified syntax, comparison operators that work on members of
+objects in a collection are implemented as parameters. Also, you can invoke a
+method on objects in a collection without referring to the automatic variable
+`$_` inside a script block. Compare the following two invocations to the
+standard syntax examples:
+
+```powershell
+Get-ChildItem Cert:\LocalMachine\Root |
+    Where-Object -Property FriendlyName -EQ 'Verisign'
+Get-ChildItem Cert:\ -Recurse |
+    ForEach-Object -MemberName GetKeyAlgorithm
+```
+
+Since the **Property** and **MemberName** parameters are positional, you can
+omit them from the command. Using aliases, you can further simplify the
+commands:
 
 ```powershell
-dir Cert:\LocalMachine\Root | where FriendlyName -eq 'Verisign'
-dir Cert:\ -Recurse | foreach GetKeyAlgorithm
+dir Cert:\LocalMachine\Root | Where FriendlyName -EQ 'Verisign'
+dir Cert:\ -Recurse | ForEach GetKeyAlgorithm
 ```
 
 While both syntaxes work, the simplified syntax returns results without
-referring to the automatic variable `$_` inside a script block.
-The method name `GetKeyAlgorithm` is treated as a parameter of `ForEach-Object`.
-The second command returns the same results, but without errors,
-because the simplified syntax does not attempt to return results for items
-for which the specified argument did not apply.
+referring to the automatic variable `$_` inside a script block. The simplified
+syntax reads more like a natural language statement and can be easier to
+understand.
+
+The method name `GetKeyAlgorithm` is passed as an argument for the
+**MemberName** parameter of `ForEach-Object`. When you invoke the method using
+the simplified syntax, the method is called for each object in pipeline only if
+that object has that method. Therefore, you get the same results, but without
+errors.
 
-In this example, the `Process` property `Description` is passed as the member name
-parameter to the `ForEach-Object` command. The results are descriptions of active
-processes.
+In the next example, `Description` is passed to the **MemberName** parameter of
+`ForEach-Object`. The command displays the description of each
+**System.Diagnostics.Process** object returned by `Get-Process`.
 
 ```powershell
 Get-Process | foreach Description
 ```
 
-In this example, the `DirectoryInfo` method `GetFiles` is passed as the member name
-parameter of the `ForEach-Object` command.
-The method is called with the search pattern parameter `.*`.
-The results are `FileInfo` records for all Unix-style hidden files in user home directories.
+In this example, the method name `GetFiles` is passed to the **MemberName**
+parameter of the `ForEach-Object` command. The `.*` value is passed to the
+**ArgumentList** parameter. The `GetFiles()` method is called with the search
+pattern parameter `.*` for each **System.IO.DirectoryInfo** object returned by
+`Get-ChildItem`.
 
 ```powershell
 Get-ChildItem /home -Directory | foreach GetFiles .*

reference/7.2/Microsoft.PowerShell.Core/About/about_Simplified_Syntax.md

@@ -1,7 +1,7 @@
 ---
 description: Describes easier, more natural-language ways of scripting filters for collections of objects.
 Locale: en-US
-ms.date: 06/09/2017
+ms.date: 04/26/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_simplified_syntax?view=powershell-7.2&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about Simplified Syntax
@@ -15,10 +15,10 @@ collections of objects.
 ## Long description
 
 Simplified syntax, introduced in Windows PowerShell 3.0, lets you build some
-filter commands without using script blocks. The simplified syntax more
-closely resembles natural language, and is primarily useful with collections
-of objects that get piped into commands `Where-Object` and `ForEach-Object` and
-their corresponding aliases `where` and `foreach`.
+filter commands without using script blocks. The simplified syntax more closely
+resembles natural language, and is primarily useful with collections of objects
+that get piped into commands `Where-Object` and `ForEach-Object` or their
+corresponding aliases `where` and `foreach`.
 
 You can use a method on the members of a collection (most commonly, an array)
 without referring to the automatic variable `$_` inside a script block.
@@ -28,41 +28,65 @@ Consider the following two invocations:
 ### Standard Syntax
 
 ```powershell
-dir Cert:\LocalMachine\Root | where { $_.FriendlyName -eq 'Verisign' }
-dir Cert:\ -Recurse | foreach { $_.GetKeyAlgorithm() }
+Get-ChildItem Cert:\LocalMachine\Root |
+    Where-Object -FilterScript { $_.FriendlyName -eq 'Verisign' }
+Get-ChildItem Cert:\ -Recurse |
+    ForEach-Object -FilterScript { $_.GetKeyAlgorithm() }
 ```
 
+> [!NOTE]
+> In the second command, the `GetKeyAlgorithm` method is called on each object
+> in the collection. If the object received from the pipeline doesn't have a
+> `GetKeyAlgorithm` method, the command produces an error.
+
 ### Simplified syntax
 
-Under the simplified syntax, comparison operators that work on members of objects in a
-collection are treated as parameters. You can invoke a method on objects in a
-collection without referring to the automatic variable `$_` inside a script block.
-Compare the following two invocations to those of the previous example:
+Under the simplified syntax, comparison operators that work on members of
+objects in a collection are implemented as parameters. Also, you can invoke a
+method on objects in a collection without referring to the automatic variable
+`$_` inside a script block. Compare the following two invocations to the
+standard syntax examples:
+
+```powershell
+Get-ChildItem Cert:\LocalMachine\Root |
+    Where-Object -Property FriendlyName -EQ 'Verisign'
+Get-ChildItem Cert:\ -Recurse |
+    ForEach-Object -MemberName GetKeyAlgorithm
+```
+
+Since the **Property** and **MemberName** parameters are positional, you can
+omit them from the command. Using aliases, you can further simplify the
+commands:
 
 ```powershell
-dir Cert:\LocalMachine\Root | where FriendlyName -eq 'Verisign'
-dir Cert:\ -Recurse | foreach GetKeyAlgorithm
+dir Cert:\LocalMachine\Root | Where FriendlyName -EQ 'Verisign'
+dir Cert:\ -Recurse | ForEach GetKeyAlgorithm
 ```
 
 While both syntaxes work, the simplified syntax returns results without
-referring to the automatic variable `$_` inside a script block.
-The method name `GetKeyAlgorithm` is treated as a parameter of `ForEach-Object`.
-The second command returns the same results, but without errors,
-because the simplified syntax does not attempt to return results for items
-for which the specified argument did not apply.
+referring to the automatic variable `$_` inside a script block. The simplified
+syntax reads more like a natural language statement and can be easier to
+understand.
+
+The method name `GetKeyAlgorithm` is passed as an argument for the
+**MemberName** parameter of `ForEach-Object`. When you invoke the method using
+the simplified syntax, the method is called for each object in pipeline only if
+that object has that method. Therefore, you get the same results, but without
+errors.
 
-In this example, the `Process` property `Description` is passed as the member name
-parameter to the `ForEach-Object` command. The results are descriptions of active
-processes.
+In the next example, `Description` is passed to the **MemberName** parameter of
+`ForEach-Object`. The command displays the description of each
+**System.Diagnostics.Process** object returned by `Get-Process`.
 
 ```powershell
 Get-Process | foreach Description
 ```
 
-In this example, the `DirectoryInfo` method `GetFiles` is passed as the member name
-parameter of the `ForEach-Object` command.
-The method is called with the search pattern parameter `.*`.
-The results are `FileInfo` records for all Unix-style hidden files in user home directories.
+In this example, the method name `GetFiles` is passed to the **MemberName**
+parameter of the `ForEach-Object` command. The `.*` value is passed to the
+**ArgumentList** parameter. The `GetFiles()` method is called with the search
+pattern parameter `.*` for each **System.IO.DirectoryInfo** object returned by
+`Get-ChildItem`.
 
 ```powershell
 Get-ChildItem /home -Directory | foreach GetFiles .*

reference/7.3/Microsoft.PowerShell.Core/About/about_Simplified_Syntax.md

@@ -1,7 +1,7 @@
 ---
 description: Describes easier, more natural-language ways of scripting filters for collections of objects.
 Locale: en-US
-ms.date: 06/09/2017
+ms.date: 04/26/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_simplified_syntax?view=powershell-7.3&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about Simplified Syntax
@@ -15,10 +15,10 @@ collections of objects.
 ## Long description
 
 Simplified syntax, introduced in Windows PowerShell 3.0, lets you build some
-filter commands without using script blocks. The simplified syntax more
-closely resembles natural language, and is primarily useful with collections
-of objects that get piped into commands `Where-Object` and `ForEach-Object` and
-their corresponding aliases `where` and `foreach`.
+filter commands without using script blocks. The simplified syntax more closely
+resembles natural language, and is primarily useful with collections of objects
+that get piped into commands `Where-Object` and `ForEach-Object` or their
+corresponding aliases `where` and `foreach`.
 
 You can use a method on the members of a collection (most commonly, an array)
 without referring to the automatic variable `$_` inside a script block.
@@ -28,41 +28,65 @@ Consider the following two invocations:
 ### Standard Syntax
 
 ```powershell
-dir Cert:\LocalMachine\Root | where { $_.FriendlyName -eq 'Verisign' }
-dir Cert:\ -Recurse | foreach { $_.GetKeyAlgorithm() }
+Get-ChildItem Cert:\LocalMachine\Root |
+    Where-Object -FilterScript { $_.FriendlyName -eq 'Verisign' }
+Get-ChildItem Cert:\ -Recurse |
+    ForEach-Object -FilterScript { $_.GetKeyAlgorithm() }
 ```
 
+> [!NOTE]
+> In the second command, the `GetKeyAlgorithm` method is called on each object
+> in the collection. If the object received from the pipeline doesn't have a
+> `GetKeyAlgorithm` method, the command produces an error.
+
 ### Simplified syntax
 
-Under the simplified syntax, comparison operators that work on members of objects in a
-collection are treated as parameters. You can invoke a method on objects in a
-collection without referring to the automatic variable `$_` inside a script block.
-Compare the following two invocations to those of the previous example:
+Under the simplified syntax, comparison operators that work on members of
+objects in a collection are implemented as parameters. Also, you can invoke a
+method on objects in a collection without referring to the automatic variable
+`$_` inside a script block. Compare the following two invocations to the
+standard syntax examples:
+
+```powershell
+Get-ChildItem Cert:\LocalMachine\Root |
+    Where-Object -Property FriendlyName -EQ 'Verisign'
+Get-ChildItem Cert:\ -Recurse |
+    ForEach-Object -MemberName GetKeyAlgorithm
+```
+
+Since the **Property** and **MemberName** parameters are positional, you can
+omit them from the command. Using aliases, you can further simplify the
+commands:
 
 ```powershell
-dir Cert:\LocalMachine\Root | where FriendlyName -eq 'Verisign'
-dir Cert:\ -Recurse | foreach GetKeyAlgorithm
+dir Cert:\LocalMachine\Root | Where FriendlyName -EQ 'Verisign'
+dir Cert:\ -Recurse | ForEach GetKeyAlgorithm
 ```
 
 While both syntaxes work, the simplified syntax returns results without
-referring to the automatic variable `$_` inside a script block.
-The method name `GetKeyAlgorithm` is treated as a parameter of `ForEach-Object`.
-The second command returns the same results, but without errors,
-because the simplified syntax does not attempt to return results for items
-for which the specified argument did not apply.
+referring to the automatic variable `$_` inside a script block. The simplified
+syntax reads more like a natural language statement and can be easier to
+understand.
+
+The method name `GetKeyAlgorithm` is passed as an argument for the
+**MemberName** parameter of `ForEach-Object`. When you invoke the method using
+the simplified syntax, the method is called for each object in pipeline only if
+that object has that method. Therefore, you get the same results, but without
+errors.
 
-In this example, the `Process` property `Description` is passed as the member name
-parameter to the `ForEach-Object` command. The results are descriptions of active
-processes.
+In the next example, `Description` is passed to the **MemberName** parameter of
+`ForEach-Object`. The command displays the description of each
+**System.Diagnostics.Process** object returned by `Get-Process`.
 
 ```powershell
 Get-Process | foreach Description
 ```
 
-In this example, the `DirectoryInfo` method `GetFiles` is passed as the member name
-parameter of the `ForEach-Object` command.
-The method is called with the search pattern parameter `.*`.
-The results are `FileInfo` records for all Unix-style hidden files in user home directories.
+In this example, the method name `GetFiles` is passed to the **MemberName**
+parameter of the `ForEach-Object` command. The `.*` value is passed to the
+**ArgumentList** parameter. The `GetFiles()` method is called with the search
+pattern parameter `.*` for each **System.IO.DirectoryInfo** object returned by
+`Get-ChildItem`.
 
 ```powershell
 Get-ChildItem /home -Directory | foreach GetFiles .*