Parameter Comments and Get-Help

[aydeisen]

In the Style guide section "Documents and Comments" under the subheading Document Each Parameter, it states that the preferred location for parameter documentation be:

within the param block, directly above each parameter. It is also possible to write .PARAMETER statements with the rest of the documentation comments, but experience shows they are more likely to be kept up-to-date if you put them closer to the code they document."

Wouldn't not populating .PARAMETER prevent someone from seeing any documentation when executing Get-Help -Parameter for the script, function, or module? If yes, what would a better alternative be that would allow Get-Help -Parameter to show the documentation for each parameter while also ensuring the coder does not need to enter the documentation twice?

[indented-automation]

No, it is a valid location for parameter help in the comment based help scheme.

This example shows it in action:

function MyFunction {
    <#
    .SYNOPSIS
        The synopsis
   
    .DESCRIPTION
        The description
    #>
    [CmdletBinding()]
    param (
        <#
            Parameter help content
        #>
        $MyParameter
    )
}

Then running Get-Help:

PS> Get-Help MyFunction -Parameter MyParameter

-MyParameter <Object>
    Parameter help content

    Required?                    false
    Position?                    1
    Default value
    Accept pipeline input?       false
    Accept wildcard characters?  false

[Jaykul]

That's exactly right. If you do not put a .PARAMETER MyParameter at the top or bottom of the function, then the comments directly above the parameter's definition will be used. I definitely think it's the best practice to do that -- keeping the documentation close to the definition makes it more likely to be kept up to date.