Edits for formatting and improving prose

Author: sdwheeler

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

@@ -1,7 +1,7 @@
 ---
 description: Describes the parameters that can be used with any cmdlet.
 Locale: en-US
-ms.date: 09/02/2025
+ms.date: 09/29/2025
 no-loc: [Debug, Verbose, Confirm]
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_commonparameters?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
@@ -417,40 +417,39 @@ Valid values are strings, the same as for any variable names.
 > always contains the final piped item from the preceding command when used in
 > a command after the blocking command.
 
-The following is an example of how `PipelineVariable` works. In this example,
-the `PipelineVariable` parameter is added to a `ForEach-Object` command to
-store the results of the command in variables. Five number are piped into the
-first `ForEach-Object` command, the results of which are stored in a variable
-named `$Temp`.
+The following example illustrates how the `PipelineVariable` works. In this
+example, five numbers are piped into the first `ForEach-Object` command. Each
+item in the pipeline is stored in the pipeline variable named `$Temp`.
 
-The results of the first `ForEach-Object` command are piped into a downstream
-`ForEach-Object` command, which displays the current values of `$Temp` and 
-`$PSItem`.
+The `Process` block of the first `ForEach-Object` command pipes the pipeline
+item into the downstream `ForEach-Object` command. The state of the variables
+is displayed in each step.
 
 ```powershell
 # Create a variable named $Temp
 $Temp = 8
 Get-Variable Temp | Format-Table
 
-# Note that the variable just created isn't available on the
-# pipeline when -PipelineVariable creates the same variable name
 $InformationPreference = 'Continue'
-Write-Information '-----------------------------------------------------------'
+Write-Information '-------------------------------------------------'
 111,222,333,444,555 | ForEach-Object -PipelineVariable Temp -Begin {
 
-  Write-Information "Upstream (Begin):   Temp = '$Temp'"
+  # Note that the newly create $Temp variable doesn't contain the value 8
+  # assigned before the pipeline started and that $PSItem is empty in
+  # the Begin block.
+  Write-Information "Upstream (Begin):   PSItem = '$PSItem', Temp = '$Temp'"
 
 } -Process {
 
-  Write-Information "Upstream (Process): Temp = '$Temp', PSItem = '$PSItem'"
-  Return $PSItem
+  Write-Information "Upstream (Process): PSItem = '$PSItem', Temp = '$Temp'"
+  return $PSItem
 
 } | ForEach-Object -Process {
 
-  Write-Information "`t`t Downstream: Temp = '$Temp', PSItem = '$PSItem'"
+  Write-Information "`tDownstream: PSItem = '$PSItem', Temp = '$Temp'"
 
 }
-Write-Information '-----------------------------------------------------------'
+Write-Information '-------------------------------------------------'
 
 # The $Temp variable is deleted when the pipeline finishes
 Get-Variable Temp | Format-Table
@@ -461,19 +460,19 @@ Name                           Value
 ----                           -----
 Temp                           8
 
------------------------------------------------------------
-Upstream (Begin):   Temp = ''
-Upstream (Process): Temp = '', PSItem = '111'
-                 Downstream: Temp = '111', PSItem = '111'
-Upstream (Process): Temp = '111', PSItem = '222'
-                 Downstream: Temp = '222', PSItem = '222'
-Upstream (Process): Temp = '222', PSItem = '333'
-                 Downstream: Temp = '333', PSItem = '333'
-Upstream (Process): Temp = '333', PSItem = '444'
-                 Downstream: Temp = '444', PSItem = '444'
-Upstream (Process): Temp = '444', PSItem = '555'
-                 Downstream: Temp = '555', PSItem = '555'
------------------------------------------------------------
+-------------------------------------------------
+Upstream (Begin):   PSItem = '', Temp = ''
+Upstream (Process): PSItem = '111', Temp = ''
+        Downstream: PSItem = '111', Temp = '111'
+Upstream (Process): PSItem = '222', Temp = '111'
+        Downstream: PSItem = '222', Temp = '222'
+Upstream (Process): PSItem = '333', Temp = '222'
+        Downstream: PSItem = '333', Temp = '333'
+Upstream (Process): PSItem = '444', Temp = '333'
+        Downstream: PSItem = '444', Temp = '444'
+Upstream (Process): PSItem = '555', Temp = '444'
+        Downstream: PSItem = '555', Temp = '555'
+-------------------------------------------------
 
 Name                           Value
 ----                           -----
@@ -486,57 +485,55 @@ Temp
 > examples, `Get-Partition` is a CDXML function and `Get-CimInstance` is a
 > CimCmdlet.
 
-1. CDXML functions use `[CmdletBinding()]`, which allows the
-   **PipelineVariable** parameter.
-
-   ```powershell
-   Get-Partition -pv pvar
-   ```
-
-   However, when you use **PipelineVariable** in Windows PowerShell v5.1, you
-   receive the following error.
-
-   ```Output
-   Get-Partition : Cannot retrieve the dynamic parameters for the cmdlet.
-   Object reference not set to an instance of an object.
-
-   At line:1 char:1
-   + get-partition -PipelineVariable pvar
-   + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-       + CategoryInfo          : InvalidArgument: (:) [Get-Partition], ParameterBindingException
-       + FullyQualifiedErrorId : GetDynamicParametersException,Get-Partition
-   ```
-
-1. When the preceding command is _not_ a CDXML command and the downstream
-   contains either command type, the **PipelineVariable** remains as the last
-   accumulated object.
-
-   ```powershell
-   Get-CimInstance Win32_DiskDrive -pv pvar |
-       ForEach-Object {
-           Write-Host "Before: $($pvar.Index)"
-           [pscustomobject]@{ DiskNumber = $_.Index }
-       } |
-       Get-Partition |
-       ForEach-Object {
-           Write-Host "After: $($pvar.Index)"
-       }
-   ```
-
-   Notice that the value of `$pvar` set to the last object in the pipeline for
-   the second `ForEach-Object` command.
-
-   ```Output
-   Before: 1
-   Before: 2
-   Before: 0
-   After: 0
-   After: 0
-   After: 0
-   After: 0
-   After: 0
-   After: 0
-   ```
+**Issue 1**: CDXML functions use `[CmdletBinding()]`, which allows the
+**PipelineVariable** parameter.
+
+```powershell
+Get-Partition -pv pvar
+```
+
+However, when you use **PipelineVariable** in Windows PowerShell v5.1, you
+receive the following error.
+
+```Output
+Get-Partition : Cannot retrieve the dynamic parameters for the cmdlet.
+Object reference not set to an instance of an object.
+
+At line:1 char:1
++ get-partition -PipelineVariable pvar
++ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    + CategoryInfo          : InvalidArgument: (:) [Get-Partition], ParameterBindingException
+    + FullyQualifiedErrorId : GetDynamicParametersException,Get-Partition
+```
+
+**Issue 2**: When the preceding command is _not_ a CDXML command and the
+downstream contains either command type, the **PipelineVariable** remains as
+the last accumulated object.
+
+```powershell
+Get-CimInstance Win32_DiskDrive -pv pvar |
+    ForEach-Object {
+        Write-Host "Upstream: Disk $($pvar.Index)"
+        return [pscustomobject]@{ DiskNumber = $_.Index }
+    } | Get-Partition | ForEach-Object {
+        Write-Host "Downstream: Disk $($pvar.Index)"
+    }
+```
+
+Notice that the value of `$pvar` set to the last object in the pipeline for
+the second `ForEach-Object` command.
+
+```Output
+Upstream: Disk 1
+Upstream: Disk 2
+Upstream: Disk 0
+Downstream: Disk 0
+Downstream: Disk 0
+Downstream: Disk 0
+Downstream: Disk 0
+Downstream: Disk 0
+Downstream: Disk 0
+```
 
 ### -ProgressAction