PowerShell Tool Help

Comment-based help is a help comment written above a function. Get-Help reads that comment and shows it to the reader, with no extra files needed.

A SYNOPSIS shows in Get-Help

The help comment sits above the function. Get-Help prints its one-line summary.

function Get-Greeting {
    <#
    .SYNOPSIS
    Returns a greeting.
    #>
    param([string]$Name)
    "Hello, $Name"
}
Get-Help Get-Greeting | Select-Object -ExpandProperty Synopsis

A full help comment describes each part

DESCRIPTION explains the function, and PARAMETER describes the Name parameter. The summary still prints the same way.

function Get-Greeting {
    <#
    .SYNOPSIS
    Returns a greeting.
    .DESCRIPTION
    Returns a greeting for the given name.
    .PARAMETER Name
    The name to greet.
    .EXAMPLE
    Get-Greeting -Name "Ana"
    #>
    param([string]$Name)
    "Hello, $Name"
}
Get-Help Get-Greeting | Select-Object -ExpandProperty Synopsis

Each tool in a suite carries its own help

A tool suite is a set of tools that belong together. Each tool has its own help comment, so Get-Help works for each one.

function Get-Greeting {
    <#
    .SYNOPSIS
    Returns a greeting.
    #>
    param([string]$Name)
    "Hello, $Name"
}
function Get-Farewell {
    <#
    .SYNOPSIS
    Returns a farewell.
    #>
    param([string]$Name)
    "Goodbye, $Name"
}
Get-Help Get-Greeting | Select-Object -ExpandProperty Synopsis
Get-Help Get-Farewell | Select-Object -ExpandProperty Synopsis

Example

function Get-Greeting {
    <#
    .SYNOPSIS
    Returns a greeting.
    .DESCRIPTION
    Returns a greeting for the given name.
    .PARAMETER Name
    The name to greet.
    .EXAMPLE
    Get-Greeting -Name "Ana"
    #>
    param([string]$Name)
    "Hello, $Name"
}
Get-Help Get-Greeting | Select-Object -ExpandProperty Synopsis
Get-Greeting -Name "Ana"

Key points

Help comment: a comment block that starts with <# and ends with #>.
SYNOPSIS: a one-line summary of what the function does.
DESCRIPTION: a longer explanation of what the function does.
PARAMETER: a description of one parameter, named after that parameter.
EXAMPLE: a sample command that shows how the function is used.
Use Get-Help with the function name to read its help.

In this example, Get-Greeting carries a full help comment with a summary, a description, a parameter description, and a sample command. Get-Help prints the summary, and calling the function still prints its greeting.

Note

Get-Help works offline for functions defined in the same script. No download is needed.

Try it Yourself

Edit the code, then press Run.

Running is simulated

function Get-Greeting {
    <#
    .SYNOPSIS
    Returns a greeting.
    .DESCRIPTION
    Returns a greeting for the given name.
    .PARAMETER Name
    The name to greet.
    .EXAMPLE
    Get-Greeting -Name "Ana"
    #>
    param([string]$Name)
    "Hello, $Name"
}
Get-Help Get-Greeting | Select-Object -ExpandProperty Synopsis
Get-Greeting -Name "Ana"

Exercise

Which marker opens a comment-based help block?

#> .SYNOPSIS Get-Help <#