Hello,
I'm learning PowerShell and I'm writing a function with parameter validation and parameter sets. When testing, I used Get-Help <myFunction> a lot to see how PowerShell interpreted my Param() block.
When I was satisfied with the results, I added Comment Based Help to my function and ran Get-Help again, only to find out that the outcome of the SYNTAX section was different: parameters were swapped, the possible values of ValidateSet didn't appear anymore and <int> was replaced by <Int32>. The behavior occurs in PowerShell and PowerShell_ISE, as well as in 2.0 and 3.0, in Windows 7 Enterprise SP1.
So I created two identical test functions, the only difference being the presence/absence of Content Based Help (.SYNOPSIS keyword):
<#
.SYNOPSIS
Comment Based Help messes up the SYNTAX section of Get-Help
#>
[CmdletBinding(DefaultParametersetName='Set3')]
Param (
[Parameter(Mandatory=$true,ParameterSetName='Set1',Position=2)]
[ValidateSet('foo','bar','baz')]
[String]$Make
,
[Parameter(Mandatory=$true,ParameterSetName='Set1',Position=1)]
[Parameter(Mandatory=$true,ParameterSetName='Set2',Position=1)]
[String]$PartName
,
[Parameter(Mandatory=$true,ParameterSetName='Set3',Position=1)]
[Parameter(Mandatory=$true,ParameterSetName='Set2',Position=2)]
[int]$PartNo
)
"ParameterSetName: $($PSCmdlet.ParameterSetName)"
"Make: $Make"
"PartName: $PartName"
"PartNo: $PartNo"
}
FunctionTEST-WithOutCommentBasedHelp {
<#
No Comment Based Help in this function
#>
[CmdletBinding(DefaultParametersetName='Set3')]
Param (
[Parameter(Mandatory=$true,ParameterSetName='Set1',Position=2)]
[ValidateSet('foo','bar','baz')]
[String]$Make
,
[Parameter(Mandatory=$true,ParameterSetName='Set1',Position=1)]
[Parameter(Mandatory=$true,ParameterSetName='Set2',Position=1)]
[String]$PartName
,
[Parameter(Mandatory=$true,ParameterSetName='Set3',Position=1)]
[Parameter(Mandatory=$true,ParameterSetName='Set2',Position=2)]
[int]$PartNo
)
"ParameterSetName: $($PSCmdlet.ParameterSetName)"
"Make: $Make"
"PartName: $PartName"
"PartNo: $PartNo"
}
When I run Get-Help on TEST-WithOutCommentBasedHelp, the result (in PS 3.0) is this:
TEST-WithOutCommentBasedHelp [-PartNo] <int> [<CommonParameters>]
TEST-WithOutCommentBasedHelp [-PartName] <string> [-Make] <string> {foo | bar | baz} [<CommonParameters>]
TEST-WithOutCommentBasedHelp [-PartName] <string> [-PartNo] <int> [<CommonParameters>]
When I run Get-Help on TEST-WithCommentBasedHelp, the result is this:
TEST-WithCommentBasedHelp [-PartNo] <Int32> [<CommonParameters>]
TEST-WithCommentBasedHelp [-Make] <String> [-PartName] <String> [<CommonParameters>]
TEST-WithCommentBasedHelp [-PartName] <String> [-PartNo] <Int32> [<CommonParameters>]
The first syntax line corresponds to ParameterSetName 'Set3', the second to 'Set1' and the third to 'Set2'.
In Set1, -PartName should come first and -Make should come second as seen in the example WITHOUT Comment Based Help. However in the example WITH Comment Based Help, -Make comes first although Position=2 and -PartName comes second even if Position=1. Also see the difference in the types. I declared -PartNo as being [Int], but the Comment Based Help version says -PartNo is Int32.
Can anyone explain what is going on here? Am I doing something wrong or is this behavior by design? If so, where can I find some explanations about this "design"?
Regards,
-=Wim=-