Help for Your Tool

A comment block at the top of a function, with keywords such as .SYNOPSIS, .DESCRIPTION, .PARAMETER and .EXAMPLE, becomes the function's help page, so Get-Help, -Examples and -Parameter explain your tool the way they explain PowerShell's own commands.

Journeyman · PowerShell · Updated

After this lesson you can

  • Write comment-based help with .SYNOPSIS, .DESCRIPTION, .PARAMETER and .EXAMPLE for a function
  • Read your own tool's help with Get-Help, -Examples and -Parameter, and fix a help block Get-Help doesn't show

Key takeaways

  • Comment-based help is a <# #> block at the top of the function, before [CmdletBinding()], that Get-Help reads as the help page.
  • .SYNOPSIS is the one-line summary, .DESCRIPTION says more, .PARAMETER Name explains one parameter, and .EXAMPLE shows a command and what it does.
  • Get-Help Add-Song, Get-Help Add-Song -Examples and Get-Help Add-Song -Parameter Mood all work on your tool.
  • Spell every keyword exactly. If one is misspelled, Get-Help ignores the whole block.

Six months from now, a friend asks to borrow your playlist tools. Or you come back to them yourself, and can't remember whether it was -Mood or -Genre, or how long a song may be. With PowerShell's own commands you'd type Get-Help (Reading Help: Get-Help). Your tools can answer the same way, with a help page you write in a comment. Every module that IT teams and developers share works like this, and it's the moment your tool stops being a script only you understand.

You need PlaylistTools.ps1 with Add-Song from Checking Input: Validation Attributes. Go to the practice folder and load it.

What Get-Help knows already

Ask for help before you've written any:

Get-Help Add-Song

NAME
    Add-Song

SYNTAX
    Add-Song [-Title] <string> [[-Artist] <string>] [-Minutes] <int> [-Mood] {Chill | Upbeat |
    Focus} [[-Path] <string>] [<CommonParameters>]


ALIASES
    None


REMARKS
    None

Get-Help built the syntax from your param() block, and even listed the three moods from [ValidateSet()]. But it can't say what the tool is for, or what a good command looks like. That part is yours to write.

The help block

A help block is a comment of many lines, between <# and #> (Your First Script), with a keyword on its own line before each part. Each keyword starts with a dot, and people write them in capitals so they stand out. Put it at the very top of the function, before [CmdletBinding()]:

function Add-Song {
    <#
    .SYNOPSIS
    Adds a song to the end of a playlist.

    .DESCRIPTION
    Add-Song adds one song to a playlist's CSV file, after checking its title,
    length and mood, and outputs the song it added.

    .PARAMETER Title
    The song's title. Required.

    .PARAMETER Minutes
    How long the song is, in whole minutes, from 1 to 15.

    .PARAMETER Mood
    Chill, Upbeat or Focus. Press Tab to fill it in.

    .EXAMPLE
    Add-Song -Title 'Tunnel Echo' -Artist 'The Night Owls' -Minutes 4 -Mood Chill

    Adds Tunnel Echo to road-trip.csv as a 4-minute Chill song.
    #>
    [CmdletBinding()]
    param(

The rest of the function stays as it was. The four keywords:

  • .SYNOPSIS: one sentence, what the tool does.
  • .DESCRIPTION: a little more, for someone deciding whether it's the right tool.
  • .PARAMETER and a parameter's name: what that parameter means, and what it accepts. One for each parameter worth explaining.
  • .EXAMPLE: a command on the first line, then a blank line and what it does. Add as many as you like; examples are what people read first.

Reading your own help

Save, load the file again, and ask:

. .\PlaylistTools.ps1
Get-Help Add-Song

NAME
    Add-Song

SYNOPSIS
    Adds a song to the end of a playlist.


SYNTAX
    Add-Song [-Title] <String> [[-Artist] <String>] [-Minutes] <Int32> [-Mood] <String> [[-Path]
    <String>] [<CommonParameters>]


DESCRIPTION
    Add-Song adds one song to a playlist's CSV file, after checking its title,
    length and mood, and outputs the song it added.


RELATED LINKS

REMARKS
    To see the examples, type: "Get-Help Add-Song -Examples"
    For more information, type: "Get-Help Add-Song -Detailed"
    For technical information, type: "Get-Help Add-Song -Full"

That's a real help page, in the same shape as Get-ChildItem's. The REMARKS point to the rest, and they work too:

Get-Help Add-Song -Examples
Get-Help Add-Song -Parameter Mood

NAME
    Add-Song

SYNOPSIS
    Adds a song to the end of a playlist.


    -------------------------- EXAMPLE 1 --------------------------

    PS > Add-Song -Title 'Tunnel Echo' -Artist 'The Night Owls' -Minutes 4 -Mood Chill

    Adds Tunnel Echo to road-trip.csv as a 4-minute Chill song.


-Mood <String>
    Chill, Upbeat or Focus. Press Tab to fill it in.

    Required?                    true
    Position?                    4
    Default value
    Accept pipeline input?       false
    Aliases
    Accept wildcard characters?  false

Get-Help filled in the facts under -Mood from param(): it's required, and it's the fourth value when you leave out the names. Add-Song -? shows the same page as Get-Help Add-Song.

When Get-Help doesn't show it

Get-Help is strict about the block. Misspell one keyword, .SYNOPIS for .SYNOPSIS, load the file, and Get-Help Add-Song shows only NAME and SYNTAX again, exactly as before you wrote any help: one wrong keyword, and Get-Help ignores the whole block, with no error. When your help doesn't appear, check three things: every keyword is spelled exactly, each starts with a dot, and the block is the first thing inside the function. (A block at the very end of the function, or right above the function line, works too; at the top, it sits right beside the code it describes.) This works the same in Windows PowerShell 5.1 and on a Mac or Linux.

Try it. Write a help block for Remove-Song, with an .EXAMPLE that rehearses with -WhatIf. Then run Get-Help Remove-Song -Examples.

Check yourself

2 questions to try on the lesson page.

So what

A tool with help explains itself to everyone who finds it, the way PowerShell's own commands do, and the person it helps most is often you, six months from now.

Key terms

Cheat sheets

Related