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
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.
µ