(GH-11248) Clarify behavior for Register-ArgumentCompleter paramete…

…rs (#11249)

* (GH-11248) Clarify behavior for `Register-ArgumentCompleter` parameters

Prior to this change, the `Register-ArgumentCompleter` reference didn't indicate that
specifying the **CommandName** parameter without the **ParameterName** or **Native**
parameters causes the command to behave as if the user specified the `-Native` switch.

This change:

- Clarifies that users should always specify the **ParameterName** parameter when
  registering an argument completer for a PowerShell command.
- Resolves #11248
- Fixes AB#281953

* (MAINT) Clarify and update `Register-ArgumentCompleter`

This change adds further clarification to various sections of
the reference documentation for `Register-ArgumentCompleter`.

It also addresses some style and formatting issues.

reference/5.1/Microsoft.PowerShell.Core/Register-ArgumentCompleter.md

@@ -2,7 +2,7 @@
 external help file: System.Management.Automation.dll-Help.xml
 Locale: en-US
 Module Name: Microsoft.PowerShell.Core
-ms.date: 12/09/2022
+ms.date: 07/10/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/register-argumentcompleter?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: Register-ArgumentCompleter
@@ -36,6 +36,12 @@ The `Register-ArgumentCompleter` cmdlet registers a custom argument completer. A
 completer allows you to provide dynamic tab completion, at run time for any command that you
 specify.
 
+When you call this command with the **CommandName** parameter and without the **ParameterName** or
+**Native** parameters, the command runs as if you specified the **Native** parameter. This prevents
+the argument completer from working for PowerShell command parameters. Always specify the
+**ParameterName** parameter when you want to register an argument completer for PowerShell
+commands.
+
 ## EXAMPLES
 
 ### Example 1: Register a custom argument completer
@@ -44,28 +50,35 @@ The following example registers an argument completer for the **Id** parameter o
 cmdlet.
 
 ```powershell
-$scriptBlock = {
-    param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameters)
+$s = {
+    param(
+        $commandName,
+        $parameterName,
+        $wordToComplete,
+        $commandAst,
+        $fakeBoundParameters
+    )
 
     (Get-TimeZone -ListAvailable).Id | Where-Object {
         $_ -like "$wordToComplete*"
     } | ForEach-Object {
-          "'$_'"
+        "'$_'"
     }
 }
-Register-ArgumentCompleter -CommandName Set-TimeZone -ParameterName Id -ScriptBlock $scriptBlock
+
+Register-ArgumentCompleter -CommandName Set-TimeZone -ParameterName Id -ScriptBlock $s
 ```
 
-The first command creates a script block which takes the required parameters which are passed in
+The first command creates a script block that takes the required parameters, which are passed in
 when the user presses <kbd>Tab</kbd>. For more information, see the **ScriptBlock** parameter
 description.
 
 Within the script block, the available values for **Id** are retrieved using the `Get-TimeZone`
 cmdlet. The **Id** property for each Time Zone is piped to the `Where-Object` cmdlet. The
-`Where-Object` cmdlet filters out any ids that do not start with the value provided by
+`Where-Object` cmdlet filters out any ids that don't start with the value provided by
 `$wordToComplete`, which represents the text the user typed before they pressed <kbd>Tab</kbd>. The
-filtered ids are piped to the `ForEach-Object` cmdlet which encloses each value in quotes, should
-the value contain spaces.
+filtered ids are piped to the `ForEach-Object` cmdlet, which encloses each value in quotes to handle
+values that contain spaces.
 
 The second command registers the argument completer by passing the scriptblock, the
 **ParameterName** **Id** and the **CommandName** `Set-TimeZone`.
@@ -77,41 +90,54 @@ cmdlet and only returns running services.
 
 ```powershell
 $s = {
-    param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameters)
-    $services = Get-Service | Where-Object {$_.Status -eq "Running" -and $_.Name -like "$wordToComplete*"}
+    param(
+        $commandName,
+        $parameterName,
+        $wordToComplete,
+        $commandAst,
+        $fakeBoundParameters
+    )
+
+    $services = Get-Service | Where-Object {
+        $_.Status -eq 'Running' -and $_.Name -like "$wordToComplete*"
+    }
+
     $services | ForEach-Object {
-        New-Object -Type System.Management.Automation.CompletionResult -ArgumentList $_.Name,
-            $_.Name,
-            "ParameterValue",
-            $_.Name
+        New-Object -Type System.Management.Automation.CompletionResult -ArgumentList @(
+            $_.Name          # completionText
+            $_.Name          # listItemText
+            'ParameterValue' # resultType
+            $_.Name          # toolTip
+        )
     }
 }
+
 Register-ArgumentCompleter -CommandName Stop-Service -ParameterName Name -ScriptBlock $s
 ```
 
-The first command creates a script block which takes the required parameters which are passed in
+The first command creates a script block that takes the required parameters, which are passed in
 when the user presses <kbd>Tab</kbd>. For more information, see the **ScriptBlock** parameter
 description.
 
 Within the script block, the first command retrieves all running services using the `Where-Object`
 cmdlet. The services are piped to the `ForEach-Object` cmdlet. The `ForEach-Object` cmdlet creates
 a new
-[`[System.Management.Automation.CompletionResult]`](/dotnet/api/system.management.automation.completionresult) object
-and populates it with the values of the current service (represented by the pipeline variable `$_`).
+[System.Management.Automation.CompletionResult](/dotnet/api/system.management.automation.completionresult)
+object and populates it with the name of the current service (represented by the pipeline variable
+`$_.Name`).
 
 The **CompletionResult** object allows you to provide additional details to each returned value:
 
 - **completionText** (String) - The text to be used as the auto completion result. This is the value
   sent to the command.
 - **listItemText** (String) - The text to be displayed in a list, such as when the user presses
-  <kbd>Ctrl</kbd>+<kbd>Space</kbd>. This is used for display only and is not passed to the command
-  when selected.
-- **resultType** ([CompletionResultType](/dotnet/api/system.management.automation.completionresulttype)) - The type of completion result.
-- **toolTip** (String) - The text for the tooltip with details to be displayed about the object.
-  This is visible when the user selects an item after pressing <kbd>Ctrl</kbd>+<kbd>Space</kbd>.
-
-The last command demonstrates that stopped services can still be passed in manually to the
-`Stop-Service` cmdlet. The tab completion is the only aspect affected.
+  <kbd>Ctrl</kbd>+<kbd>Space</kbd>. PowerShell uses this for display only. It isn't passed to the
+  command when selected.
+- **resultType**
+  ([CompletionResultType](/dotnet/api/system.management.automation.completionresulttype)) - The
+  type of completion result.
+- **toolTip** (String) - The text for the tooltip with details to display about the object. This is
+  visible when the user selects an item after pressing <kbd>Ctrl</kbd>+<kbd>Space</kbd>.
 
 ### Example 3: Register a custom Native argument completer
 
@@ -123,28 +149,47 @@ example adds tab-completion for the `dotnet` Command Line Interface (CLI).
 
 ```powershell
 $scriptblock = {
-    param($wordToComplete, $commandAst, $cursorPosition)
-        dotnet complete --position $cursorPosition $commandAst.ToString() | ForEach-Object {
-            [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
-        }
+    param(
+        $wordToComplete,
+        $commandAst,
+        $cursorPosition
+    )
+
+    dotnet complete --position $cursorPosition $commandAst.ToString() | ForEach-Object {
+        [System.Management.Automation.CompletionResult]::new(
+            $_,               # completionText
+            $_,               # listItemText
+            'ParameterValue', # resultType
+            $_                # toolTip
+        )
+    }
 }
+
 Register-ArgumentCompleter -Native -CommandName dotnet -ScriptBlock $scriptblock
 ```
 
-The first command creates a script block which takes the required parameters which are passed in
+The first command creates a script block that takes the required parameters, which are passed in
 when the user presses <kbd>Tab</kbd>. For more information, see the **ScriptBlock** parameter
 description.
 
-Within the script block, the `dotnet complete` command is used to perform the tab completion.
-The results are piped to the `ForEach-Object` cmdlet which use the **new** static method of the
-[System.Management.Automation.CompletionResult](/dotnet/api/system.management.automation.completionresult) class
-to create a new **CompletionResult** object for each value.
+Within the script block, the `dotnet complete` command performs the tab completion. The results are
+piped to the `ForEach-Object` cmdlet, which uses the **new** static method of the
+[System.Management.Automation.CompletionResult](/dotnet/api/system.management.automation.completionresult)
+class to create a **CompletionResult** object for each value.
 
 ## PARAMETERS
 
 ### -CommandName
 
-Specifies the name of the commands as an array.
+Specifies the name of one or more commands to register the argument completer for. This parameter
+is mandatory for native commands.
+
+When you specify this parameter without the **ParameterName** or **Native** parameters, the command
+behaves as if you had specified the **Native** parameter. When registering argument completers for
+PowerShell commands, always specify the **ParameterName** parameter.
+
+If you don't specify this parameter, PowerShell registers the argument completer for the specified
+**ParameterName** across all PowerShell commands.
 
 ```yaml
 Type: System.String[]
@@ -160,7 +205,7 @@ Accept wildcard characters: False
 
 ### -Native
 
-Indicates that the argument completer is for a native command where PowerShell cannot complete
+Indicates that the argument completer is for a native command where PowerShell can't complete
 parameter names.
 
 ```yaml
@@ -177,11 +222,16 @@ Accept wildcard characters: False
 
 ### -ParameterName
 
-Specifies the name of the parameter whose argument is being completed. The parameter name specified
-cannot be an enumerated value, such as the **ForegroundColor** parameter of the `Write-Host` cmdlet.
+Specifies the name of the parameter the argument completer applies to. The type for specified
+parameters can't be an enumeration, such as the **ForegroundColor** parameter of the `Write-Host`
+cmdlet.
 
 For more information on enums, see [about_Enum](./About/about_Enum.md).
 
+When registering an argument completer for PowerShell commands, always specify this parameter. When
+you specify the **CommandName** parameter without the **ParameterName** or **Native** parameters,
+the command behaves as if you specified the **Native** parameter.
+
 ```yaml
 Type: System.String
 Parameter Sets: PowerShellSet
@@ -201,35 +251,41 @@ the values that complete the input. The script block must unroll the values usin
 (`ForEach-Object`, `Where-Object`, etc.), or another suitable method. Returning an array of values
 causes PowerShell to treat the entire array as **one** tab completion value.
 
+The script block can also return
+[System.Management.Automation.CompletionResult](/dotnet/api/system.management.automation.completionresult)
+objects for each value to enhance the user experience. Returning **CompletionResult** objects
+enables you to define tooltips and custom list entries displayed when users press
+<kbd>Ctrl</kbd>+<kbd>Space</kbd> to show the list of available completions.
+
 The script block must accept the following parameters in the order specified below. The names of the
 parameters aren't important because PowerShell passes in the values by position.
 
-- `$commandName` (Position 0) - This parameter is set to the name of the
+- `$commandName` (Position 0, **String**) - This parameter is set to the name of the
   command for which the script block is providing tab completion.
-- `$parameterName` (Position 1) - This parameter is set to the parameter
+- `$parameterName` (Position 1, **String**) - This parameter is set to the parameter
   whose value requires tab completion.
-- `$wordToComplete` (Position 2) - This parameter is set to value the user has provided before they
-  pressed <kbd>Tab</kbd>. Your script block should use this value to determine tab completion
-  values.
-- `$commandAst` (Position 3) - This parameter is set to the Abstract Syntax
+- `$wordToComplete` (Position 2, **String**) - This parameter is set to value the user has provided
+  before they pressed <kbd>Tab</kbd>. Your script block should use this value to determine tab
+  completion values.
+- `$commandAst` (Position 3, **CommandAst**) - This parameter is set to the Abstract Syntax
   Tree (AST) for the current input line. For more information, see
-  [Ast Class](/dotnet/api/system.management.automation.language.ast).
-- `$fakeBoundParameters` (Position 4) - This parameter is set to a hashtable containing the
-  `$PSBoundParameters` for the cmdlet, before the user pressed <kbd>Tab</kbd>. For more information,
-  see [about_Automatic_Variables](./About/about_Automatic_Variables.md).
+  [CommandAst Class](/dotnet/api/system.management.automation.language.commandast).
+- `$fakeBoundParameters` (Position 4 **IDictionary**) - This parameter is set to a hashtable
+  containing the `$PSBoundParameters` for the cmdlet, before the user pressed <kbd>Tab</kbd>. For
+  more information, see [about_Automatic_Variables](./About/about_Automatic_Variables.md).
 
 When you specify the **Native** parameter, the script block must take the following parameters in
 the specified order. The names of the parameters aren't important because PowerShell passes in the
 values by position.
 
-- `$wordToComplete` (Position 0) - This parameter is set to value the user has provided before they
-  pressed <kbd>Tab</kbd>. Your script block should use this value to determine tab completion
-  values.
-- `$commandAst` (Position 1) - This parameter is set to the Abstract Syntax
-  Tree (AST) for the current input line. For more information, see
-  [Ast Class](/dotnet/api/system.management.automation.language.ast).
-- `$cursorPosition` (Position 2) - This parameter is set to the position of the cursor when the user
-  pressed <kbd>Tab</kbd>.
+- `$wordToComplete` (Position 0, **String**) - This parameter is set to value the user has provided
+  before they pressed <kbd>Tab</kbd>. Your script block should use this value to determine tab
+  completion values.
+- `$commandAst` (Position 1, **CommandAst**) - This parameter is set to the Abstract Syntax Tree
+  (AST) for the current input line. For more information, see
+  [CommandAst Class](/dotnet/api/system.management.automation.language.commandast).
+- `$cursorPosition` (Position 2, **Int32**) - This parameter is set to the position of the cursor
+  when the user pressed <kbd>Tab</kbd>.
 
 You can also provide an **ArgumentCompleter** as a parameter attribute. For more information, see
 [about_Functions_Advanced_Parameters](./About/about_Functions_Advanced_Parameters.md).
@@ -250,7 +306,8 @@ Accept wildcard characters: False
 
 This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable,
 -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose,
--WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](./About/about_CommonParameters.md).
+-WarningAction, and -WarningVariable. For more information, see
+[about_CommonParameters](./About/about_CommonParameters.md).
 
 ## INPUTS
 
@@ -267,3 +324,5 @@ This cmdlet returns no output.
 ## NOTES
 
 ## RELATED LINKS
+
+[about_Functions_Argument_Completion](./About/about_Functions_Argument_Completion.md)