How to Write Comment-Based Help for PowerShell Scripts

1. Comment-Based Help in PowerShell
2. Comment-Based Keywords in PowerShell

This article demonstrates how we can write comment-based help topics for scripts and functions. We will use special help comment keywords to create the topics.

We use the Get-Help cmdlet to display comment-based help topics similar to those generated by XML files.

Comment-Based Help in PowerShell

Illustrated below is the syntax for comment-based help.

# .<help keyword>
# <help content>

or

<#
.<help keyword>
<help content>
#>

We write comment-based help topics as a series of comments. To mark comments, we can either add the # symbol at the beginning of every comment line or use <# and #> to create a comment block.

The console will register the lines within the comment block as comments.

We use special keywords to define each section of a comment-based topic help. Keywords start with a . and are not case-sensitive.

Here is an example:

<#
.Description
Get-Clipboard fetches the content of our clipboard in the session.
#>

In the example above, the .Description keyword marks the comment as the description of our function.

A comment block must have at least one keyword. Some keywords only appear once, while others do not have a limit.

The content for a keyword should begin on the line immediately after the keyword and does not have a limit.

When adding comment-based help for functions, you can add them in any of the three locations discussed below.

1. At the start of the function body.
2. At the end of the function body.
3. Before the function keyword. Separated by no more than one blank line.

Examples:

function Get-Function
{
<#
.<help keyword>
<content>
#>

  # function logic
}

or

function Get-Function
{
   # function logic

<#
.<help keyword>
<content>
#>
}

or

<#
.<help keyword>
<content>
#>
function Get-Function { }

Comments-based help for scripts can either appear at the beginning of the script or the end. Here are some examples:

<#
.<help keyword>
<content>
#>

function Get-Function { }

or

function Get-Function { }

<#
.<help keyword>
<content>
#>

Comment-Based Keywords in PowerShell

Listed below are the valid comment-based help keywords. They can appear in any order, and they are not case-sensitive.

.SYNOPSIS

This is a short description of the function or script. The keyword should only appear once in each topic.

.DESCRIPTION

This is a detailed description of a function or script. We use it only once in each topic.

.PARAMETER

This describes the parameters in your script or function. We add a .PARAMETER keyword for every parameter in our scripts or functions.

.PARAMETER <Parameter-Name>

Parameter keywords do not follow a strict order in the comment block. The syntax of the parameters in the script or function will determine the order in the help topic.

You can change the order by changing the syntax.

We can specify the parameter keyword content by adding a comment in or function or script. This comment should precede the parameter variable name.

PowerShell prioritizes the description associated with the parameter keyword over the syntax comment where both are used.

<#
.SYNOPSIS
    Brief description
#>
function Noun-Verb {
    [CmdletBinding()]
    param (
        # It is the same as .Parameter
        [string]$CompName
    )
    # Logic
}

.EXAMPLE

Include a sample command that employs the script or function. We can include this keyword for all the examples in our script or function.

.INPUTS

These are the .NET objects that we can pipe to our script or function. We can add a description for the input objects.

.OUTPUTS

These are the .NET objects that our cmdlet returns. We can add a description for the returned objects.

.NOTES

These are any additional information about the script or function. The information can include the date it’s coded, the function name, or the creator’s name.

.LINK

These are the related topics.

Here is an example of comment-based help for a function:

In conclusion, we can add comment-based help in functions or scripts by placing them in a comment block. When adding help topics, use the keyword we discussed above and remember where to place the comment blocks for scripts and functions.