PowerShell Comment-Based Help

Comment-based help is help text written as a comment inside a function. Get-Help reads that comment and prints it back as help.

A help comment does not change the output

The help comment starts with <# and ends with #>. The function still runs exactly as before.

function Get-Greeting {
  <#
  .SYNOPSIS
  Says hello to a person.
  #>
  param([string]$Name = "Ana")
  "Hello, $Name"
}
Get-Greeting -Name "Ana"

The full comment shape

A full comment block adds a description, a note for each parameter, and a sample call. Each part has its own heading.

function Get-Greeting {
  <#
  .SYNOPSIS
  Says hello to a person.
  .DESCRIPTION
  Prints a greeting for the given name.
  .PARAMETER Name
  The name to greet.
  .EXAMPLE
  Get-Greeting -Name "Ana"
  #>
  param([string]$Name = "Ana")
  "Hello, $Name"
}
Get-Greeting

Get-Help reads the comment back

Get-Help on the function prints the synopsis and description from the comment. No help file is needed.

function Get-Greeting {
  <#
  .SYNOPSIS
  Says hello to a person.
  .DESCRIPTION
  Prints a greeting for the given name.
  .PARAMETER Name
  The name to greet.
  .EXAMPLE
  Get-Greeting -Name "Ana"
  #>
  param([string]$Name = "Ana")
  "Hello, $Name"
}
Get-Help Get-Greeting

Example

function Get-Greeting {
  <#
  .SYNOPSIS
  Says hello to a person.
  .DESCRIPTION
  Prints a greeting for the given name.
  .PARAMETER Name
  The name to greet.
  .EXAMPLE
  Get-Greeting -Name "Ana"
  #>
  param([string]$Name = "Ana")
  "Hello, $Name"
}
Get-Greeting
(Get-Help Get-Greeting).Synopsis

Key points

Comment-based help: help text written as a comment block inside a function.
Synopsis: a one-line summary of what the function does.
Description: a longer explanation of what the function does.
Parameter note: a short note for one parameter, written under its .PARAMETER heading.
Example note: a sample call, written under the .EXAMPLE heading.
Get-Help: the command that reads the comment block and prints the help text.

In this example, the function is defined with its full help comment, then it runs, and Get-Help reads the synopsis back from the comment.

Note

the comment block sits inside the function, just above its param block.

Try it Yourself

Edit the code, then press Run.

Running is simulated

function Get-Greeting {
  <#
  .SYNOPSIS
  Says hello to a person.
  .DESCRIPTION
  Prints a greeting for the given name.
  .PARAMETER Name
  The name to greet.
  .EXAMPLE
  Get-Greeting -Name "Ana"
  #>
  param([string]$Name = "Ana")
  "Hello, $Name"
}
Get-Greeting
(Get-Help Get-Greeting).Synopsis

Exercise

Which heading holds the one-line summary of a function?

.SYNOPSIS .DESCRIPTION .PARAMETER .EXAMPLE