PowerShell: Adding Help to PowerShell Scripts

Introduction

PowerShell allows you to write help for Get-Help using block comments.
The help you create will be displayed when running Get-Help <script file>.

Writing Comment-Based Help

In PowerShell, you can write block comments (comments spanning multiple lines) by using <# and #>.
By writing comments that start with help keywords, Get-Help will display those comments.

For more details, please refer to Comment-Based Help Keywords.
The main help keywords are listed below.

Keyword	Keyword Description
.SYNOPSIS	A brief description of the script, concisely explaining what the script does in 1 to 3 lines.
.DESCRIPTION	A detailed description of the script; this section can only be used once within a single help topic.
.PARAMETER <param>	Description of the arguments (parameters) used when calling the script. Write the argument after the keyword, followed by the description of the argument in the help body.
.EXAMPLE	Examples of actually using the script, described for each individual example.

How to Write Help Comments

Comment-based help, or "help comments," are written as follows:

<#
  .SYNOPSIS
    <Brief help>
    ・
    ・
    ・

As shown, write the help keyword after a space following the block comment header <#.
Then, write the body of the help below it. Repeat this for each help keyword.

The created help can be displayed using the Get-Help cmdlet. The output will look like this:

> Get-Help .\help-function.ps1

NAME
    help-function\help-function.ps1

SYNOPSIS
    test -help option script


SYNTAX
   help-function\help-function.ps1 [-h] [-help] [<CommonParameters>]
.
.
.

Important Notes when Writing Help Comments

When writing help comments, you need to keep the following points in mind. If these rules are violated, the help you created will not be displayed, and only the bare minimum usage information will be shown.

• Do not include other comments inside the help comment block.
  If you write regular comments before the help keywords, they will not be recognized as help comments. Header comments and similar notes must be written as separate comments.

  • Incorrect Example

    <#
     # <Header comment>
    
      .SYNOPSIS
        test -help option script
    
    

  • Correct Example

    ##
    # <Header comment>
    #
    <#
      .SYNOPSIS
        test -help option script
    
    

• Indent your help content.
  Help keywords (such as .SYNOPSIS) must be indented. If you don't indent them—meaning you write them without any leading spaces—they will not be recognized as help keywords.
  The help body text (the line following .SYNOPSIS) does not necessarily need to be indented. However, for readability, it's better to indent the help text so it is clearly part of the help content.

  • No indentation (Help will not be displayed)

    <#
      .SYNOPSIS
        test -help option script
    
    

  • No indentation for body text (Help will be displayed)

    <#
      .SYNOPSIS
    test -help option script
    
    

  • With indentation

    <#
      .SYNOPSIS
        test -help option script
    
    

In the correct case, running Get-Help <script> will display the help defined in the comments.

Otherwise, a simple help message like the following will be displayed:

> Get-Help ./help-function.ps1
help-function.ps1 [-h] [-help]

Summary

I have briefly explained how to write help for PowerShell scripts. If the script is in your path, you can view the help using Get-Help, and completion will also work.