CODEWITHSUNDEEP
powershellpowershell-2.0
Aaron Jensen
Aaron Jensen

Reputation: 26819

How do I get help messages to appear for my Powershell script parameters?

I have a powershell script (setup.ps1), that we use as the entry point for our development environment setup scripts. It takes a parameter:

param(
    [Parameter(Position=0,HelpMessage="The targets to run.")]
    [Alias("t")]
    [string[]]
    $Targets = "Help"
)

When I run

PS > get-help .\setup.ps1 -detailed

in the parameters section, my help message doesn't appear:

PARAMETERS
    -Targets <String[]>

What do I need to do to get my parameter help messages to display?

Upvotes: 87

Views: 111537

Answers (4)

Jeff
Jeff

Reputation: 238

Line spacing is critical. See https://learn.microsoft.com/en-us/powershell/scripting/developer/help/placing-comment-based-help-in-scripts?view=powershell-7.4

If the first item in the script body (after the Help) is a function declaration, there must be at least two blank lines between the end of the script Help and the function declaration. Otherwise, the Help is interpreted as being Help for the function, not Help for the script.

Upvotes: 0

Andreas Covidiot
Andreas Covidiot

Reputation: 4765

one just needs the <# .SYNOPSIS #> part on top of the file to make it work and you can comment your params nicely inline:

<# .SYNOPSIS #>
param(
   [String]$foo   ## my 1st cool param
  ,[Switch]$bar  ## my 2nd crazy switch
)
...

(checked with PS 5.1.14409.1018)

Upvotes: 14

iRon
iRon

Reputation: 23830

Apparently if you have a help header defined, you can just use a remark (#) behind the parameter (in this example: #The targets to run.):

<#
.SYNOPSIS
    .
.DESCRIPTION
    .
.PARAMETER Path
    The path to the .
.PARAMETER LiteralPath
    Specifies a path to one or more locations. Unlike Path, the value of 
    LiteralPath is used exactly as it is typed. No characters are interpreted 
    as wildcards. If the path includes escape characters, enclose it in single
    quotation marks. Single quotation marks tell Windows PowerShell not to 
    interpret any characters as escape sequences.
#>

Param(
    [String]$Targets = "Help"   #The targets to run.
)

Results in:

PS C:\> Get-help .\Setup.ps1 -Detailed

NAME
    C:\Setup.ps1

SYNOPSIS
    .


SYNTAX
    C:\Setup.ps1 [[-Targets] <String>] [<CommonParameters>]


DESCRIPTION
    .


PARAMETERS
    -Targets <String>
        The targets to run.

Upvotes: 31

Keith Hill
Keith Hill

Reputation: 202062

You put a certain style of comment at the top of the file that can be decoded by the PowerShell help system. Here's an example:

<#
.SYNOPSIS
    .
.DESCRIPTION
    .
.PARAMETER Path
    The path to the .
.PARAMETER LiteralPath
    Specifies a path to one or more locations. Unlike Path, the value of 
    LiteralPath is used exactly as it is typed. No characters are interpreted 
    as wildcards. If the path includes escape characters, enclose it in single
    quotation marks. Single quotation marks tell Windows PowerShell not to 
    interpret any characters as escape sequences.
.EXAMPLE
    C:\PS> 
    <Description of example>
.NOTES
    Author: Keith Hill
    Date:   June 28, 2010    
#>
function AdvFuncToProcessPaths
{
    [CmdletBinding(DefaultParameterSetName="Path")]
    param(
        [Parameter(Mandatory=$true, Position=0, ParameterSetName="Path", 
                   ValueFromPipeline=$true, 
                   ValueFromPipelineByPropertyName=$true,
                   HelpMessage="Path to ...")]
        [ValidateNotNullOrEmpty()]
        [string[]]
        $Path,

        [Alias("PSPath")]
        [Parameter(Mandatory=$true, Position=0, ParameterSetName="LiteralPath", 
                   ValueFromPipelineByPropertyName=$true,
                   HelpMessage="Path to ...")]
        [ValidateNotNullOrEmpty()]
        [string[]]
        $LiteralPath
    )
    ...

For more info see the help topic - man about_comment_based_help.

Upvotes: 121

Related Questions