Fix Test-Remainder invocation to pass three arguments, not two. (#12831)

* Fix Test-Remainder invocation to pass three arguments, not two.

You state: "The following example declares a Value parameter that's mandatory and a Remaining parameter that accepts **all the remaining parameter values** that are submitted to the function.

You want to demonstrate this with this invocation:
`Test-Remainder first one, two`

But your "all the remaining parameter values" is merely one value: `one, two` is an array.
Thus, if you removed `ValueFromRemainingArguments`, the same invocation would yield the same output, so your example **does not** demonstrate the benefit of `ValueFromRemainingArguments`.
To fix it, three args have to be passed to the Cmdlet, not just two.

* Improve Test-Remainder examples

---------

Co-authored-by: Sean Wheeler <sean.wheeler@microsoft.com>

Author: derkallevombau

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

@@ -1,7 +1,7 @@
 ---
 description: Explains how to add parameters to advanced functions.
 Locale: en-US
-ms.date: 01/18/2026
+ms.date: 03/10/2026
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_functions_advanced_parameters?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about_Functions_Advanced_Parameters
@@ -576,40 +576,36 @@ The `ValueFromRemainingArguments` argument indicates that the parameter accepts
 all the parameter's values in the command that aren't assigned to other
 parameters of the function.
 
-There's a known issue for using collections with
-**ValueFromRemainingArguments** where the passed-in collection is treated as a
+Collections passed to **ValueFromRemainingArguments** are always treated as a
 single element.
 
-The following example demonstrates this known issue. The **Remaining**
-parameter should contain **one** at **index 0** and **two** at **index 1**.
-Instead, both elements are combined into a single entity.
-
 ```powershell
 function Test-Remainder {
     param(
         [Parameter(Mandatory, Position=0)]
         [string]$Value,
 
-        [Parameter(Position=1, ValueFromRemainingArguments)]
+        [Parameter(ValueFromRemainingArguments, Position=1)]
         [string[]]$Remaining
     )
 
-    "Found $($Remaining.Count) elements"
+    "Value = $Value"
+    "Found $($Remaining.Count) remaining values"
 
     for ($i = 0; $i -lt $Remaining.Count; $i++) {
         "${i}: $($Remaining[$i])"
     }
 }
-Test-Remainder first one, two
 ```
 
-```Output
-Found 1 elements
-0: one two
-```
+```powershell
+PS> Test-Remainder first one two, three
 
-> [!NOTE]
-> This issue is resolved in PowerShell 6.2.
+Value = first
+Found 2 remaining values
+0: one
+1: two three
+```
 
 #### HelpMessage argument
 

reference/7.4/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md

@@ -1,7 +1,7 @@
 ---
 description: Explains how to add parameters to advanced functions.
 Locale: en-US
-ms.date: 01/18/2026
+ms.date: 03/10/2026
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_functions_advanced_parameters?view=powershell-7.4&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about_Functions_Advanced_Parameters
@@ -581,23 +581,54 @@ function Test-Remainder {
         [Parameter(Mandatory, Position=0)]
         [string]$Value,
 
-        [Parameter(Position=1, ValueFromRemainingArguments)]
+        [Parameter(ValueFromRemainingArguments, Position=1)]
         [string[]]$Remaining
     )
 
-    "Found $($Remaining.Count) elements"
+    "Value = $Value"
+    "Found $($Remaining.Count) remaining values"
 
     for ($i = 0; $i -lt $Remaining.Count; $i++) {
         "${i}: $($Remaining[$i])"
     }
 }
-Test-Remainder first one, two
 ```
 
-```Output
-Found 2 elements
+```powershell
+PS> Test-Remainder first one two three
+
+Value = first
+Found 3 remaining values
 0: one
 1: two
+2: three
+```
+
+Beginning in PowerShell 6.2, collections are handled differently when passed to
+**ValueFromRemainingArguments**. If you only pass a collection, then each value
+in the collection is treated as a separate item.
+
+```powershell
+PS> Test-Remainder first one, two, three
+
+Value = first
+Found 3 remaining values
+0: one
+1: two
+2: three
+```
+
+When you pass multiple values where at least one isn't a collection, the
+collection is treated as a single item.
+
+```powershell
+PS> Test-Remainder first one, two three four
+
+Value = first
+Found 3 remaining values
+0: one two
+1: three
+2: four
 ```
 
 #### HelpMessage argument

reference/7.5/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md

@@ -1,7 +1,7 @@
 ---
 description: Explains how to add parameters to advanced functions.
 Locale: en-US
-ms.date: 01/18/2026
+ms.date: 03/10/2026
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_functions_advanced_parameters?view=powershell-7.5&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about_Functions_Advanced_Parameters
@@ -581,23 +581,54 @@ function Test-Remainder {
         [Parameter(Mandatory, Position=0)]
         [string]$Value,
 
-        [Parameter(Position=1, ValueFromRemainingArguments)]
+        [Parameter(ValueFromRemainingArguments, Position=1)]
         [string[]]$Remaining
     )
 
-    "Found $($Remaining.Count) elements"
+    "Value = $Value"
+    "Found $($Remaining.Count) remaining values"
 
     for ($i = 0; $i -lt $Remaining.Count; $i++) {
         "${i}: $($Remaining[$i])"
     }
 }
-Test-Remainder first one, two
 ```
 
-```Output
-Found 2 elements
+```powershell
+PS> Test-Remainder first one two three
+
+Value = first
+Found 3 remaining values
 0: one
 1: two
+2: three
+```
+
+Beginning in PowerShell 6.2, collections are handled differently when passed to
+**ValueFromRemainingArguments**. If you only pass a collection, then each value
+in the collection is treated as a separate item.
+
+```powershell
+PS> Test-Remainder first one, two, three
+
+Value = first
+Found 3 remaining values
+0: one
+1: two
+2: three
+```
+
+When you pass multiple values where at least one isn't a collection, the
+collection is treated as a single item.
+
+```powershell
+PS> Test-Remainder first one, two three four
+
+Value = first
+Found 3 remaining values
+0: one two
+1: three
+2: four
 ```
 
 #### HelpMessage argument

reference/7.6/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md

@@ -1,7 +1,7 @@
 ---
 description: Explains how to add parameters to advanced functions.
 Locale: en-US
-ms.date: 01/18/2026
+ms.date: 03/10/2026
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_functions_advanced_parameters?view=powershell-7.6&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about_Functions_Advanced_Parameters
@@ -581,23 +581,54 @@ function Test-Remainder {
         [Parameter(Mandatory, Position=0)]
         [string]$Value,
 
-        [Parameter(Position=1, ValueFromRemainingArguments)]
+        [Parameter(ValueFromRemainingArguments, Position=1)]
         [string[]]$Remaining
     )
 
-    "Found $($Remaining.Count) elements"
+    "Value = $Value"
+    "Found $($Remaining.Count) remaining values"
 
     for ($i = 0; $i -lt $Remaining.Count; $i++) {
         "${i}: $($Remaining[$i])"
     }
 }
-Test-Remainder first one, two
 ```
 
-```Output
-Found 2 elements
+```powershell
+PS> Test-Remainder first one two three
+
+Value = first
+Found 3 remaining values
 0: one
 1: two
+2: three
+```
+
+Beginning in PowerShell 6.2, collections are handled differently when passed to
+**ValueFromRemainingArguments**. If you only pass a collection, then each value
+in the collection is treated as a separate item.
+
+```powershell
+PS> Test-Remainder first one, two, three
+
+Value = first
+Found 3 remaining values
+0: one
+1: two
+2: three
+```
+
+When you pass multiple values where at least one isn't a collection, the
+collection is treated as a single item.
+
+```powershell
+PS> Test-Remainder first one, two three four
+
+Value = first
+Found 3 remaining values
+0: one two
+1: three
+2: four
 ```
 
 #### HelpMessage argument