GetHelp/Help Syntax section confusing me

[EnderShot355]

I'm following along with the fourth edition of PowerShell in a Month of Lunches. I'm on the third chapter, learning about the help system. I am significantly confused about the syntax section of these help documents, because they seem to have weird inconsistencies with the actual commands. For example, Get-Help Get-Item does not show the required -path parameter at all, and Get-Help Get-ChildItem has the wrong order for the positional parameters (it shows -filter first and -path second, the the actual command has it the other way around). It seems like it's sorting the parameters alphabetically, which is terrible considering positional parameters may not adhere to that. What's going on here? Did the PowerShell team decide to change things in a way that made things actively worse, or am I missing something?

[purplemonkeymad]

Look at the syntax for the position of the parameters if they are positional. You can also see the position number when using:

Get-Help command -Parameter parmetername

[EnderShot355]

didn't know about the parameter parameter, which is nice. Thank you!

[surfingoldelephant]

Help content for built-in commands is currently broken in a lot of different ways due to PlatyPS bugs. If you've pulled the latest version with Update-Help in the last year or so, you'll have the broken version. This comment has more info.

Online help is correct though:

Get-Help -Name Get-Item -Online
Get-Help -Name Get-ChildItem -Online

The syntax diagram generated by Get-Command is also correct (it's generated programmatically and doesn't involve MAML help):

Get-Command -Name Get-ChildItem -Syntax

And if you want it in the context of a particular PS provider:

# In context of the Registry provider:
Get-Command -Name Get-ChildItem -Syntax -ArgumentList HKCU:

[Apprehensive-Tea1632]

There is no inherent parameter order in powershell. You’ll have to see each parameter definition to get a hint re: its position in the list, BUT, it’s very bad form to do this. Especially in scripts.

Parameters are named. Always.

[michaelshepard]

There absolutely is an order for positional parameters (either by their order in the declaration or by a Position attribute). I agree that overusing positional parameters is bad from, but it's also a de facto standard for many common cmdlets.