Example for Register-ArgumentCompleter -Native has wrong parameter names

[Jawz84]

The naming of the scriptblock parameters in the example for the native argument completer are misleading/incorrect. This is the example:

$scriptblock = {
     param($commandName, $wordToComplete, $cursorPosition)
         dotnet complete --position $cursorPosition "$wordToComplete" | ForEach-Object {
            [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
         }
 }
Register-ArgumentCompleter -Native -CommandName dotnet -ScriptBlock $scriptblock

When I set a breakpoint inside the scriptblock, I find that $commandName is of type String, and $wordToComplete is of type CommandAst. The $commandName variable holds the last 'partial word' on the command line, the word to complete.

This matches with what I found after digging in the code, at this line, the exact same pattern is used: CompletionCompleter.cs:1307

It seems to me the parameters in the example scriptblock should be named:
$wordToComplete, $commandAst, $cursorPosition

The example does work, because $commandAst.ToString() returns the full command line up to that point (eg. "dotnet --h"), and dotnet uses the --position x information to filter out where to start completing.

Proposed improved example:

$scriptblock = {
     param($wordToComplete, $commandAst, $cursorPosition)
         dotnet complete --position $cursorPosition $commandAst.ToString() | ForEach-Object {
            [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
         }
 }
Register-ArgumentCompleter -Native -CommandName dotnet -ScriptBlock $scriptblock

---

Edit:

I realized later that there is more. The description for the -ScriptBlock parameter combined with the -Native parameter needs to be corrected too.

Current text:

$commandName (Position 0) - This parameter is set to the name of the command for which the script block is providing tab completion.
$wordToComplete (Position 1) - This parameter is set to value the user has provided before they pressed Tab. Your script block should use this value to determine tab completion values.
$cursorPosition (Position 2) - This parameter is set to the position of the cursor when the user pressed Tab.

Suggested improved version, adapted from the parameter description for non-Native:

$wordToComplete (Position 0) - This parameter is set to value the user has provided before they pressed Tab. 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.
$cursorPosition (Position 2) - This parameter is set to the position of the cursor when the user pressed Tab.

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 0050f0cf-2744-391c-5b15-b4eeb51f8675
• Version Independent ID: 3d52e60a-f772-66e7-adf6-9ad79acdae0f
• Content: Register-ArgumentCompleter (Microsoft.PowerShell.Core)
• Content Source: reference/7.0/Microsoft.PowerShell.Core/Register-ArgumentCompleter.md
• Product: powershell
• GitHub Login: @SteveL-MSFT
• Microsoft Alias: slee

[Jawz84]

I'm willing to take this one on and write a PR for it.

[Jawz84]

@sdwheeler can I ask what the usual time frame is for merged changes to appear live on the website? Just curious what I can expect. Thanks!

[sdwheeler]

@Jawz84 It is a manual process. I try to publish to the live site once a week.

[Jawz84]

@sdwheeler thank you! I think you guys are doing an amazing job.