# 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 November 10, 2026 ## 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: ```powershell Get-Help Add-Song ``` ```text NAME Add-Song SYNTAX Add-Song [-Title] [[-Artist] ] [-Minutes] [-Mood] {Chill | Upbeat | Focus} [[-Path] ] [] 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()]`: ```powershell 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: ```powershell . .\PlaylistTools.ps1 Get-Help Add-Song ``` ```text NAME Add-Song SYNOPSIS Adds a song to the end of a playlist. SYNTAX Add-Song [-Title] [[-Artist] ] [-Minutes] [-Mood] [[-Path] ] [] 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: ```powershell Get-Help Add-Song -Examples Get-Help Add-Song -Parameter Mood ``` ```text 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 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 - [Comment-Based Help](https://www.ask-codey.com/glossary/comment-based-help) - [Get-Help](https://www.ask-codey.com/glossary/get-help) - [Comment](https://www.ask-codey.com/glossary/comment-powershell) ## Cheat sheets - [Help for Your Tool](https://www.ask-codey.com/cheat-sheets/powershell-comment-based-help-cheat-sheet) ## Related - [Reading Help: Get-Help](https://www.ask-codey.com/lessons/powershell-get-help) - [Your First Script](https://www.ask-codey.com/lessons/powershell-your-first-script) - [\`-WhatIf\` in Your Own Tools](https://www.ask-codey.com/lessons/powershell-supports-should-process) - [Exercise: The Playlist Tools](https://www.ask-codey.com/lessons/exercise-powershell-the-playlist-tools) Source: https://www.ask-codey.com/lessons/powershell-comment-based-help