One of the greatest tools to assist with learning PowerShell is the help system, and specifically the Get-Help cmdlet. This cmdlet is one of the three key cmdlets in learning PowerShell, the other two being Get-Command and Get-Member. If you've ever used PowerShell, you've most likely used Get-Help (or one of its aliases, help and man.)
Help Automatically Installed with PowerShell
Help is automatically installed with PowerShell, but if you're using PowerShell version 3 or greater, remember to execute the Update-Help cmdlet the first time you use PowerShell, and regularly thereafter, as Microsoft is being really good at adding new topics and correcting errors they and others find in the existing help. (By letting you use Update-Help on your system, Microsoft saves you a considerable amount of disk space, only downloading to your system the language support you've defined for your system, rather than have to ship every possible language your machine may have specified.)
The help you get from PowerShell is only part of the picture, though. You can provide similar help for the users of the functions and scripts you write, using the comment-based help feature the PowerShell team added in PowerShell version 2. In that version, they added the ability to include multi-line comments to your scripts. The delimiters for these comments are the '<#' and '#>' character pairs, and are used like this.
# Any single line comment <# Any number of lines can be included in comments here. #>
How Help Comes Into Play
So how does help come into play? It's actually pretty straightforward. By defining just a few keywords into the comment, and adding the comment at the beginning of your script, or the beginning of your function, anyone using your script or function can get help the same way you get results from Get-Help.
The keywords you'll use are referred to as tags, and the basic tags I use are .SYNOPSIS, .DESCRIPTION, and .EXAMPLE. The .SYNOPSIS tag allows you to provide a concise definition of what the script or function does. The .DESCRIPTION tag allows you to provide greater details, and the .EXAMPLE tag allows you to add usage examples to guide the user to the proper way to call your script or function. Here's the comment section from a script I use to set the database owner for all databases to 'sa'.
<# .Synopsis Sets the database owner to SA for all Databases in the Instance. .DESCRIPTION This script will evaluate each database on the specified instance, and if the owner property is set to anything other than sa, it will change it to SA. .EXAMPLE ./Set-DatabaseOwnerToSA.ps1 WS12SQL .EXAMPLE ./Set-DatabaseOwnerToSA.ps1 WS12SQL\SQL01 #>
You can also use tags like .PARAMETER to describe the parameters used in your code, .INPUTS to describe the type of objects that may be piped into your code, or .OUTPUTS to describe what's sent to the pipeline, .NOTES to provide additional information, .LINK to provide links to additional references and more.
Providing this kind of help for your scripts or functions will help those who use your code to understand what it does and how to use it, and I've found it helps me remember how to use scripts I've written some time ago, too.
