Locations for Comment-based Help in PowerShell Functions

One of the first things you'll learn when beginning with PowerShell is how to use the help system. When working from the PowerShell console, I use the help function and omit the Name parameter since it's positional and then specify the name of the cmdlet that I'm looking for help on as shown in the following example.

1help Get-HotFix

help-locations1a.png

This same type of standardized help can be added to your PowerShell functions and scripts which makes it easy for others to learn how to use them. It's called comment based help and it can be placed in one of three locations but there are some caveats to two of the options.

Me personally, I prefer to write my code in such a way that it works the same way no matter what the scenario is and it operates trouble free even when someone else needs to modify it. This is why I personally choose to place my comment based help just inside the function declaration:

 1function Test-HelpLocation {
 2
 3<#
 4.SYNOPSIS
 5    Creates a new PowerShell function in the specified location.
 6
 7.DESCRIPTION
 8    New-MrFunction is an advanced function that creates a new PowerShell function in the
 9    specified location including creating a Pester test for the new function.
10
11.PARAMETER Name
12    Name of the function.
13
14.PARAMETER Path
15    Path of the location where to create the function. This location must already exist.
16
17.EXAMPLE
18     New-MrFunction -Name Get-MrPSVersion -Path "$env:ProgramFiles\WindowsPowerShell\Modules\MyModule"
19
20.INPUTS
21    None
22
23.OUTPUTS
24    System.IO.FileInfo
25
26.NOTES
27    Author:  Mike F Robbins
28    Website: http://mikefrobbins.com
29    Twitter: @mikefrobbins
30#>
31
32    [CmdletBinding()]
33    param (
34        $ComputerName = $env:COMPUTERNAME
35    )
36
37    Write-Output "Does Something to $ComputerName"
38
39}

If someone downloads a copy of one of my functions from GitHub and accidentally places multiple carriage returns before or after the comment based help, it still works without issue. I've also found that the average PowerShell script module creator places multiple functions inside of a script module file (PSM1) and this options allows anyone to clearly be able to determine what help goes with which function and it also allows the function and its help to be collapsed together.

Another option is to place the comment based help prior to the function declaration:

 1<#
 2.SYNOPSIS
 3    Creates a new PowerShell function in the specified location.
 4
 5.DESCRIPTION
 6    New-MrFunction is an advanced function that creates a new PowerShell function in the
 7    specified location including creating a Pester test for the new function.
 8
 9.PARAMETER Name
10    Name of the function.
11
12.PARAMETER Path
13    Path of the location where to create the function. This location must already exist.
14
15.EXAMPLE
16     New-MrFunction -Name Get-MrPSVersion -Path "$env:ProgramFiles\WindowsPowerShell\Modules\MyModule"
17
18.INPUTS
19    None
20
21.OUTPUTS
22    System.IO.FileInfo
23
24.NOTES
25    Author:  Mike F Robbins
26    Website: http://mikefrobbins.com
27    Twitter: @mikefrobbins
28#>
29
30function Test-HelpLocation2 {
31    [CmdletBinding()]
32    param (
33        $ComputerName = $env:COMPUTERNAME
34    )
35
36    Write-Output "Does Something to $ComputerName"
37}

There's two reasons I don't like this option. If more than one empty line exists between the help and the function, it simply won't work as PowerShell assumes the help is intended for the script itself and not the function. This option also doesn't allow the help to be collapsed with the function so if you happen to place more than one function inside a PSM1 script module file, it's less than optimal (at least in my opinion).

The third option is to place the help at the bottom of the function just inside the closing curly brace for the function:

 1function Test-HelpLocation3 {
 2    [CmdletBinding()]
 3    param (
 4        $ComputerName = $env:COMPUTERNAME
 5    )
 6
 7    Write-Output "Does Something to $ComputerName"
 8
 9<#
10.SYNOPSIS
11    Creates a new PowerShell function in the specified location.
12
13.DESCRIPTION
14    New-MrFunction is an advanced function that creates a new PowerShell function in the
15    specified location including creating a Pester test for the new function.
16
17.PARAMETER Name
18    Name of the function.
19
20.PARAMETER Path
21    Path of the location where to create the function. This location must already exist.
22
23.EXAMPLE
24     New-MrFunction -Name Get-MrPSVersion -Path "$env:ProgramFiles\WindowsPowerShell\Modules\MyModule"
25
26.INPUTS
27    None
28
29.OUTPUTS
30    System.IO.FileInfo
31
32.NOTES
33    Author:  Mike F Robbins
34    Website: http://mikefrobbins.com
35    Twitter: @mikefrobbins
36#>
37
38}

While this location is valid for functions, it isn't valid for scripts when they're digitally signed which means my code couldn't be written this way in all scenarios so that particular option is out since I want all of my code written in a standardized format.

Ultimately where you decide to place comment based help is a personal preference and you should follow your organizations standards or the project creators standards if you're contributing to someone else's code. See the about_Comment_Based_Help topic for more information on comment based help.

µ