How to write comment based Help in PowerShell?

In PowerShell when you create a complex script or function then it should be essential to create help for the end-users to easily understand your script functionality. Writing comment-based help or XML-based help, at the end is similar to Get-Help syntax for cmdlets or function which is the online version of help.

For Example, Just open the PowerShell console and run the command below.

Get-Help Get-WmiObject

And you can see the various help sections in the output like NAME, SYNOPSIS, SYNTAX, DESCRIPTION, PARAMETER, LINK. These are called Keywords. We can include all of them in the script of function manually to get the help. Whenever we use the help keyword, you need to use the dot (.) keyword before it.

When we write comment-based help, it should be inside the multiline comment box <# .. #>. You can also use single line comment # but for users who can easily read and understand it is recommended to put them inside the multiline comment box.

It is not necessary to use the syntax in capital letters but again for user's readability and to distinguish the keywords, we put them into CAPS letters.

Below is the structure of the command based help.

<#
.HELP Keyword
HELP content
#>

Let’s understand some necessary keywords one by one.

• .SYNOPSIS − Brief description of the function or the script. This keyword can be used only once in the help section.

• .DESCRIPTION − Detailed description of the function or the script. This keyword can be used only once in the help section.

• .PARAMETER − It is for the brief description of the parameter. You need to write a new parameter keyword for each parameter. First, you need to write the parameter keyword and space the name of the parameter and in the next line, the content of the parameter.

• .Example − A sample command describing the function or the script. You can also include the sample output. Multiple examples can be added with each new Example keyword.

• .Inputs − Description of the input object.

• .Outputs − Description of the output object.

The above keywords included are the common keywords which help users to get enough idea about the function or script related help. There are also many other keywords you can include. To get more information about the keywords, use the help section for the about_comment-based_help.

get-help about_comment-based_help

Example

function Get-ColoredService{
<#
.SYNOPSIS
Gets the colored output of the Services based on Status

.DESCRIPTION
Get-ColoredService will provide the colorful output based on the status of the service.
If the Service is in Stopped status - Output will be Red
If the service is in Running status - Output will be in Green

.
#>

}

When you check the help of the above function you will get the below output.

PS C:\WINDOWS\system32> Get-Help Get-ColoredService
NAME
Get-ColoredService

SYNOPSIS
Gets the colored output of the Services based on Status

SYNTAX
Get-ColoredService []

DESCRIPTION
Get-ColoredService will provide the colorful output based on the status of the service.
If the Service is in Stopped status - Output will be Red
If the service is in Running status - Output will be in Green

.
REMARKS
To see the examples, type: "get-help Get-ColoredService -examples".
For technical information, type: "get-help Get-ColoredService -full".

You can see the few help keywords (Name, Syntax, Description, Related Links, Remarks) are the default.

We will now create help with other keywords like parameter, inputs, outputs, example etc. Whatever you declare as a parameter in param block, the syntax will be shown for it as described in the below example.

function Get-ColoredService{
<#
.SYNOPSIS
Gets the colored output of the Services based on Status

.DESCRIPTION
Get-ColoredService will provide the colorful output based on the status of the service.
If the Service is in Stopped status - Output will be Red
If the service is in Running status - Output will be in Green

.PARAMETER ServiceName
Specifies the path to the CSV-based input file.
.EXAMPLE
Get-ColoredService -ServiceName Spooler,WinRM
.EXAMPLE
Get-ColoredService -ServiceName *
.INPUTS
Input single or multiple services names
.OUTPUTS
Output of the services information in the table format
#>

[cmdletbinding()]
param(
[string[]]\$ServiceName
)

}

When you check the help of the above function, you can see the variable name in the Syntax.

PS C:\WINDOWS\system32> Get-Help Get-ColoredService -Full
NAME
Get-ColoredService
SYNOPSIS
Gets the colored output of the Services based on Status

SYNTAX
Get-ColoredService [[-ServiceName] <String[]>] [<CommonParameters>]

DESCRIPTION
Get-ColoredService will provide the colorful output based on the status of the service.
If the Service is in Stopped status - Output will be Red
If the service is in Running status - Output will be in Green

PARAMETERS
-ServiceName <String[]>
Specifies the path to the CSV-based input file.

Required?                      false
Position?                      1
Default value
Accept pipeline input?         false
Accept wildcard characters?    false

<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug, ErrorAction, ErrorVariable, WarningAction, WarningVariable, OutBuffer, PipelineVariable, and OutVariable. For more information,
see

INPUTS
Input single or multiple services name

OUTPUTS
Output of the services information in the table format

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

PS C:\>Get-ColoredService -ServiceName Spooler,WinRM

-------------------------- EXAMPLE 2 --------------------------

PS C:\>Get-ColoredService -ServiceName *

RELATED LINKS