Why does PowerShell help show incorrect or confusing parameter syntax?
Asked by
MistyCedar42
I'm working through the fourth edition of PowerShell in a Month of Lunches and am currently learning about the help system. The syntax sections in some help documents are confusing because they don't seem to match how the commands actually work. For example, Get-Help Get-Item doesn't show the required -Path parameter, while Get-Help Get-ChildItem appears to list -Filter before -Path even though their positional behavior suggests the opposite. It looks as if the parameters might be sorted alphabetically, which seems especially misleading when positional parameters are involved. Is this a change in PowerShell, a problem with the help files, or am I misunderstanding how the syntax display works?
Answers
Some of the locally installed help for built-in commands is genuinely inaccurate because of issues in the documentation-generation tooling. If you recently ran Update-Help, you may have downloaded affected content. The online help is generally more accurate, so you can try Get-Help -Name Get-Item -Online or Get-Help -Name Get-ChildItem -Online. Another reliable option is Get-Command -Name Get-ChildItem -Syntax, since that syntax is generated directly from the command metadata. You can also provide -ArgumentList when you want to see syntax in the context of a particular provider, such as the Registry provider.
Reply to this answer
For a specific parameter, use Get-Help with the -Parameter option—for example, Get-Help Get-ChildItem -Parameter Path. That output shows whether the parameter is positional and what its position number is. The syntax display itself isn’t always the best way to determine that.
Reply to this answer
PowerShell parameters are named, and scripts are usually clearer and safer when they use names explicitly rather than relying on positional arguments. That said, positional parameters do exist: a parameter can have a defined position, and common commands often support them. Check each parameter’s metadata to see its position instead of assuming the visual order in the help syntax is meaningful.
NorthPebble6: There is an actual position for positional parameters, either assigned through metadata or determined by the command declaration. Although relying on positional arguments too heavily is poor style, it is common for frequently used commands, so the position information still matters.
Reply to this answer
Add your answer
Answers are reviewed before publication.
MistyCedar42: I didn’t know about the -Parameter option. That clears up how to inspect the details for an individual parameter.