Back to top

FREE eBook: The Most USEFUL PowerShell CmdLets and more…

Grab a copy!

Step By Step Approach How To Write Comment-Based Help For PowerShell Scripts And CmdLets

Written by Dejan Mladenović in PowerShell Essentials

Share this post:

Share on Pinterest Share on Reddit Share on LinkedIn

PowerShell Help for functions, CmdLets, and scripts can be written:

  • internally as comment-based help in the script.
  • externally as an XML file and this is required for Updateable Help.

In this article, I describe how to write PowerShell help internally as comment-based help which is personally my preferred style.

Before we dive in writing our own help content let’s first look at how we can get PowerShell help for some CmdLets and what we get with it. If you want to go straight to steps than please read this subheading How To Write PowerShell Help Step By Step

How To Display Help Content For A PowerShell CmdLet, Functions And More

To get help in PowerShell we use the following options:

  • Get-Help CmdLet 
Get-Help Get-Service
  • help function to display one page of help content at the time 
help Get-Service
  • man is just an alias for the help function 
man Get-Service
  • cmdlet-name -? 
Get-Service -?

All the previous examples will give the same result as shown on a screenshot below.

Help content for Get-Service CmdLet

Notice that in the result on the screenshot above we have several sections:

  • NAME,
  • SYNOPSIS,
  • SYNTAX,
  • DESCRIPTION,
  • RELATED LINKS,
  • REMARKS.

Some of the sections are auto-generated (Explained in Step 12 of the step by step guide) and some of them can be written by comment-based help writers explained in the section How To Write PowerShell Help Step by Step.

Also, notice that we have several switch parameters for help results which defines the level of details that help will show us as a result (I have shown each option in the next section Examples Of Own CmdLets Help Content):

  • Default
  • Examples
  • Detailed
  • Full
  • Online 
Get-Help Get-Service -Examples

Get-Help Get-Service -Detailed

Get-Help Get-Service -Full

Get-Help Get-Service -Online

If you want to get the help for the script then use Path parameter and point to script file location like in this example:

Get-Help -Path "C:\Temp\GetCPUInfo.ps1" -Full

I have created a Free eBook “The Most USEFUL PowerShell CmdLets and more…” with a list of recommended readings from the PowerShell help system and a list of useful PowerShell CmdLets and functions. So please feel free to download it from here and let me know what you think so I can make it even more useful.

Have you ever wondered is it possible to have help with the same feel and look in your own CmdLets and scripts? So simple answer is: yes it is possible and I will show you how in the following sections.

Examples Of Own CmdLets Help Content

In this example, I will use my own Get-CPUInfo CmdLet which is part of the Efficiency Booster PowerShell Project. This project is a library of CmdLets which helps us IT experts to efficiently accomplish our daily IT tasks.

Please feel free to download the source code from the zip file so you can easily follow me along.

Let me quickly show you some examples of my own CmdLet help content and which of the sections we get using different switch parameters.

Example 1 – Default Comment-Based Help

Get-Help Get-CPUInfo

Here is the result of calling help for my own CmdLet and notice that we get the same sections as in the previous example (with Get-Service CmdLet): Name, Synopsis, Syntax, Description, Related Links, and Remarks.

Default Command-Based help content

Example 2 – Detailed Comment-Based Help

Let’s try one more example with a little bit more details in the help result.

Get-Help Get-CPUInfo -Detailed

We get these sections in addition: Parameters, and Examples.

Detailed Comment-Based Help with two additional sections: Parameters, and Examples

Example 3 – Full Comment-Based Help

Let’s try the option with full help explanation of CmdLet

Get-Help Get-CPUInfo -Full

Notice that we get additional data: More data in the parameters section (Required?, Position?, Default value, Accept pipeline input?, and Accept wildcard character?), Inputs, and Outputs sections in addition.

Full Comment-Based Help with additional info in the Parameters section
Full Comment-Based Help with additional Inputs, and Outputs sections

Example 4 – Example Comment-Based Help

If we want to focus on example calls of CmdLet than we use example parameter.

Get-Help Get-CPUInfo -Example

Notice we get Name, Synopses and Examples sections.

Examples Comment-Based Help

Example 5 – Parameter Comment-Based Help

If we want to get help content just for a particular parameter we use the following syntax:

Get-Help Get-CPUInfo -Parameter computers

Here is help content for “computers” parameter:

Parameter Comment-Based Help

As you can see my own CmdLet has the help result that is the same feel and look as Microsoft PowerShell CmdLets delivered with the PowerShell, but How have we achieved that? Well, just continue reading and I will show you exactly that.

PowerShell Comment-Based Help – Tips

We are just one step from the Step By Step Guide but before I show you that I would like to give you some tips that might help you speed up the process:

TIP 1: To be more efficient in writing CmdLet Help faster there is PowerShell ISE Add-on New-CommentBlock CmdLet written and explained in this article. It demands small additional work but I think it pays off in the long run so I highly recommend reading the article and implementing the code.

TIP 2: Use PowerShell Comment-Based Help Template that I have written for you so you do not start from scratch like shown in step by step guide. You can fill out the template following step by step guide.

How To Write PowerShell Help Step By Step

Here are the steps that I follow when I want to create comment-based help for my own CmdLets.

Step 1: Create a comment block starting with <# and end with #> within the region created in the previous step.

<#

#>

Step 2: Within the comment block, we will repeat the serious of help keywords using this pattern:

.Help_Keyword 
Help text

Step 3: SYNOPSES keyword is a short description of function or script and it can be used only once. 

<#
.SYNOPSIS
Get CPU info for a list of computers.
#>

Step 4: DESCRIPTION keyword is a longer and more detailed description of function or script and it can be used only once as well. 

<#
.SYNOPSIS
Get CPU info for a list of computers.
.DESCRIPTION
Gets CPU info for a list of servers. 
List of servers is in txt file in 01servers folder or list of strings with names of computers.
CmdLet has two ParameterSets one for the list of computers from file and another from a list of strings as computer names.
#>

Step 5: PARAMETER keyword explains each parameter in the function or script syntax. Repeat this keyword as many times as many parameters function or script has. 

<#
.SYNOPSIS
Get CPU info for a list of computers.
.DESCRIPTION
Gets CPU info for a list of servers. 
List of servers is in txt file in 01servers folder or list of strings with names of computers.
CmdLet has two ParameterSets one for a list of computers from file and another from a list of strings as computer names.
.PARAMETER computers
List of computers that we want to get CPU Info from. Parameter belongs to default Parameter Set = ServerNames.
.PARAMETER filename
Name of txt file with a list of servers that we want to check CPUInfo. .txt file should be in the 01servers folder.
Parameter belongs to Parameter Set = FileName.
.PARAMETER errorlog
Switch parameter that sets to write to log or not to write to the log. Error file is in PSLog folder with name Error_Log.txt.
.PARAMETER client
OK - O client
BK - B client
etc.
.PARAMETER solution
FIN - Financial solution
HR - Human resource solution
etc.
#>

Step 6: EXAMPLE keyword is a sample command that uses the function or script and it should be repeated for each example that we want to describe.

TIP: I use the following template and just repeat it for each example that I wants to present:

.EXAMPLE
<"Example code">

Description
---------------------------------------
<"Explanation of example">
<#
.SYNOPSIS
Get CPU info for a list of computers.
.DESCRIPTION
Gets CPU info for a list of servers. 
List of servers is in txt file in 01servers folder or list of strings with names of computers.
CmdLet has two ParameterSets one for a list of computers from file and another from a list of strings as computer names.
.PARAMETER computers
List of computers that we want to get CPU Info from. Parameter belongs to default Parameter Set = ServerNames.
.PARAMETER filename
Name of txt file with a list of servers that we want to check CPUInfo. .txt file should be in the 01servers folder.
Parameter belongs to Parameter Set = FileName.
.PARAMETER errorlog
Switch parameter that sets to write to log or not to write to the log. Error file is in PSLog folder with the name Error_Log.txt.
.PARAMETER client
OK - O client
BK - B client
etc.
.PARAMETER solution
FIN - Financial solution
HR - Human resource solution
etc.
.EXAMPLE
Get-CPUInfo -client "OK" -solution "FIN"

Description
---------------------------------------
Test of default parameter with default value ( computers = 'localhost' ) in default ParameterSet = ServerName.

.EXAMPLE
Get-CPUInfo -client "OK" -solution "FIN" -Verbose

Description
---------------------------------------
Test of the Verbose parameter. NOTE: Notice how the localhost default value of parameter computers replaces with the name of the server.
#>

Step 7: INPUTS keyword describes types of objects that can be piped to the function or script. 

<#
.SYNOPSIS
Get CPU info for a list of computers.
.DESCRIPTION
Gets CPU info for a list of servers. 
List of servers is in txt file in 01servers folder or list of strings with names of computers.
CmdLet has two ParameterSets one for a list of computers from file and another from a list of strings as computer names.
.PARAMETER computers
List of computers that we want to get CPU Info from. Parameter belongs to default Parameter Set = ServerNames.
.PARAMETER filename
Name of txt file with a list of servers that we want to check CPUInfo. .txt file should be in the 01servers folder.
Parameter belongs to Parameter Set = FileName.
.PARAMETER errorlog
Switch parameter that sets to write to log or not to write to the log. Error file is in PSLog folder with the name Error_Log.txt.
.PARAMETER client
OK - O client
BK - B client
etc.
.PARAMETER solution
FIN - Financial solution
HR - Human resource solution
etc.
.EXAMPLE
Get-CPUInfo -client "OK" -solution "FIN"

Description
---------------------------------------
Test of default parameter with default value ( computers = 'localhost' ) in default ParameterSet = ServerName.

.EXAMPLE
Get-CPUInfo -client "OK" -solution "FIN" -Verbose

Description
---------------------------------------
Test of the Verbose parameter. NOTE: Notice how the localhost default value of parameter computers replaces with the name of the server.

.INPUTS
System.String
#>

Step 8: OUTPUTS keyword describes the type of objects that the CmdLet returns.

<#
.SYNOPSIS
Get CPU info for a list of computers.
.DESCRIPTION
Gets CPU info for a list of servers. 
List of servers is in txt file in 01servers folder or list of strings with names of computers.
CmdLet has two ParameterSets one for a list of computers from file and another from a list of strings as computer names.
.PARAMETER computers
List of computers that we want to get CPU Info from. Parameter belongs to default Parameter Set = ServerNames.
.PARAMETER filename
Name of txt file with list of servers that we want to check CPUInfo. .txt file should be in the 01servers folder.
Parameter belongs to Parameter Set = FileName.
.PARAMETER errorlog
Switch parameter that sets to write to log or not to write to the log. Error file is in PSLog folder with the name Error_Log.txt.
.PARAMETER client
OK - O client
BK - B client
etc.
.PARAMETER solution
FIN - Financial solution
HR - Human resource solution
etc.
.EXAMPLE
Get-CPUInfo -client "OK" -solution "FIN"

Description
---------------------------------------
Test of default parameter with default value ( computers = 'localhost' ) in default ParameterSet = ServerName.

.EXAMPLE
Get-CPUInfo -client "OK" -solution "FIN" -Verbose

Description
---------------------------------------
Test of the Verbose parameter. NOTE: Notice how the localhost default value of parameter computers replaces with the name of the server.

.INPUTS
System.String

.OUTPUTS
System.Management.Automation.PSCustomObject
#>

Step 9: NOTES keyword has additional information about the function or script. Like for example function name, Create By, Date coded, etc. 

<#
.SYNOPSIS
Get CPU info for a list of computers.
.DESCRIPTION
Gets CPU info for a list of servers. 
List of servers is in txt file in 01servers folder or list of strings with names of computers.
CmdLet has two ParameterSets one for a list of computers from file and another from a list of strings as computer names.
.PARAMETER computers
List of computers that we want to get CPU Info from. Parameter belongs to default Parameter Set = ServerNames.
.PARAMETER filename
Name of txt file with a list of servers that we want to check CPUInfo. .txt file should be in the 01servers folder.
Parameter belongs to Parameter Set = FileName.
.PARAMETER errorlog
Switch parameter that sets to write to log or not to write to the log. Error file is in PSLog folder with the name Error_Log.txt.
.PARAMETER client
OK - O client
BK - B client
etc.
.PARAMETER solution
FIN - Financial solution
HR - Human resource solution
etc.
.EXAMPLE
Get-CPUInfo -client "OK" -solution "FIN"

Description
---------------------------------------
Test of default parameter with default value ( computers = 'localhost' ) in default ParameterSet = ServerName.

.EXAMPLE
Get-CPUInfo -client "OK" -solution "FIN" -Verbose

Description
---------------------------------------
Test of the Verbose parameter. NOTE: Notice how the localhost default value of parameter computers replaces with the name of the server.

.INPUTS
System.String

.OUTPUTS
System.Management.Automation.PSCustomObject

.NOTES
FunctionName : 
Created by   : Author
Date Coded   : 10/31/2019 19:06:41
More info    : http://improvescripting.com/
#>

Step 10: LINK keyword reference related topics or commands. Repeat link help keyword for each related topic that we want to show. 

<#
.SYNOPSIS
Get CPU info for a list of computers.
.DESCRIPTION
Gets CPU info for a list of servers. 
List of servers is in txt file in 01servers folder or list of strings with names of computers.
CmdLet has two ParameterSets one for a list of computers from file and another from a list of strings as computer names.
.PARAMETER computers
List of computers that we want to get CPU Info from. Parameter belongs to default Parameter Set = ServerNames.
.PARAMETER filename
Name of a text file with a list of servers that we want to check CPUInfo. .txt file should be in the 01servers folder.
Parameter belongs to Parameter Set = FileName.
.PARAMETER errorlog
Switch parameter that sets to write to log or not to write to the log. Error file is in PSLog folder with the name Error_Log.txt.
.PARAMETER client
OK - O client
BK - B client
etc.
.PARAMETER solution
FIN - Financial solution
HR - Human resource solution
etc.
.EXAMPLE
Get-CPUInfo -client "OK" -solution "FIN"

Description
---------------------------------------
Test of default parameter with default value ( computers = 'localhost' ) in default ParameterSet = ServerName.

.EXAMPLE
Get-CPUInfo -client "OK" -solution "FIN" -Verbose

Description
---------------------------------------
Test of the Verbose parameter. NOTE: Notice how the localhost default value of parameter computers replaces with the name of the server.

.INPUTS
System.String

.OUTPUTS
System.Management.Automation.PSCustomObject

.NOTES
FunctionName : 
Created by   : Author
Date Coded   : 10/31/2019 19:06:41
More info: http://improvescripting.com/

.LINK 
Get-CimInstance -Class Win32_Processor
#>

Step 11: Here is the list of auto-generated content keywords created by parsing the script or function syntax:

  • Name
  • Syntax
  • Parameter List
  • Common Parameters
  • Parameter Attribute Table
  • Remarks

Step 12: Here are help keywords that I have not covered in this step by step guidance since I did not use them but it is good to know about them.

  • .COMPONENT
  • .ROLE
  • .FUNCTIONALITY
  • .FORWARDHELPTARGETNAME
  • .FORWARDHELPCATEGORY
  • .REMOTEHELPRUNSPACE
  • .EXTERNALHELP

Step 13: Test your Help content (Using Get-Help CmdLet) just like you would test your PowerShell code.

Where To Put Comment-Based Help

Personally I like to put comment-based help in front of the Function keyword.

Other locations to put comment-based help are:

  • at the beginning of the function body
  • at the end of the function body.

TIP: Here is how I organize my code using region tags:

  • IMPORTANT: I do not use region help anymore since this breaks the functionality of comment-based help. Instead, comment-based help can collapse to own region.
  • Function region – here is all the function code.
  • Execution examples region – here I write different calls to CmdLet.
Organization of code with #region #endregion tags

PowerShell Comment-Based Help Template

Use this template as a starting point so you do not need to write help from scratch every time, just fill out the keywords with help text and repeat some keywords as needed (like EXAMPLE, PARAMETER).

     <#
        .SYNOPSIS
        .DESCRIPTION
        .PARAMETER
        .EXAMPLE
        .INPUTS
        .OUTPUTS
        .NOTES
            FunctionName : 
            Created by   : 
            Date Coded   : 
        .LINK
            
Home

     #>

NOTE: If you do not want to copy and paste this template the other option is the use of PowerShell ISE Add-on New-CommentBlock CmdLet written and explained in this article. This Add-on help you to get the same template on just one click of the menu item.

How To Update Online Help

IMPORTANT: It is important to run the Windows PowerShell Console as Administrator since the user needs permissions to write to disk.

Start Window PowerShell Console as Administrator and run the following command to update PowerShell Help content:

Update-Help

IMPORTANT: Here are some limitations of Update-Help CmdLet

  • Runs only once-per-day
  • has a version checking and installs only files that are newer than the existing files
  • downloads are limited to 1 GB of uncompressed content per module

NOTE: To avoid these limitations use Force parameter of Update-Help CmdLet.

Update-Help -Force

How To Download Help Files And Save Them On File Share?

Save help for all modules on the file share using Save-Help CmdLet.

Save-Help -DestinationPath "\\FileServer01\FileShare01\Help"

Save help more than one time each day then use the Force parameter and to avoid other limitations mentioned in the previous section.

Save-Help -Force -DestinationPath "\\FileServer01\FileShare01\Help"

How To Install Help On The Server Without Internet Access?

  1. Download the help files from the internet and save them on the file share. Run Save-Help CmdLet on the server that has an internet connection.
  2. Then Run Update-Help CmdLet on the server that has no internet connection with SourcePath parameter pointing to file share location where Help files are downloaded to like in the following example.
Save-Help -DestinationPath "\\FileServer01\FileShare01\Help"

Update-Help -SourcePath \\FileServer01\FileShare01\Help -Credential DomainName\AdminName

Can Help Be Shown In Other Languages Than English?

Get-Help can get help articles for all supported languages and locales and PowerShell Get-Help CmdLet will use Windows settings (Settings -> Region & Languages) to decide whether to show help in a locale set or primary locale but you have to Update help with that locale on your machine.

For example, here we update help with both French and English help. 

Update-Help -UICulture fr-FR, en-US

Difference Between Comment-Based Help And Parameter’s HelpMessage Argument

It is useful to differentiate the usage of the Parameter keyword in comment-based help and HelpMessage Argument when creating the parameters in functions.

I have explained this difference in the post How To Create Parameters In PowerShell.

How To Get “about_” Help Topics

“About” help topics start with a word about and they are conceptual articles in Powershell and include articles about the PowerShell Language.

To get the list of all about topics installed on your computer run this command:

Get-Help about_*

I have created a Free eBook “The Most USEFUL PowerShell CmdLets and more…” with a list of recommended readings from the PowerShell help system and a list of useful PowerShell CmdLets and functions. So please feel free to download it from here and let me know what you think so I can make it even more useful.

Here is a screenshot from Free eBook

Useful PowerShell Comment-Based Help Articles

Here are some useful articles and resources:

Useful PowerShell Commands

I have put together some useful PowerShell commands used in this article:

Get-Help Get-Service

help Get-Service 

man Get-Service

Get-Service -?

Update-Help 

Update-Help -UICulture fr-FR, en-US

Save-Help -Force -DestinationPath "\\FileServer01\FileShare01\Help"

Get-Help about_*

Related Questions

Where Is PowerShell Documentation

If you want to read more about PowerShell use these two links to PowerShell Online Documentation:

Useful Reading

I have created a Free eBook “The Most USEFUL PowerShell CmdLets and more…” with a list of recommended readings from the PowerShell help system and a list of useful PowerShell CmdLets and functions. So please feel free to download it from here and let me know what you think so I can make it even more useful.

Well Done, you read the whole article!
Now you do not need help with how to write the help.

About Dejan Mladenović

Post Author Dejan MladenovicHey Everyone! I hope that this article you read today has taken you from a place of frustration to a place of joy coding! Please let me know of anything you need for Windows PowerShell in the comments below that can help you achieve your goals!
I have 18+ years of experience in IT and you can check my Microsoft credentials. Transcript ID: 750479 and Access Code: DejanMladenovic
Credentials
About Me...

My Posts | Website

Share this post:

Share on Pinterest Share on Reddit Share on LinkedIn

Dejan Mladenović

Hey Everyone! I hope that this article you read today has taken you from a place of frustration to a place of joy coding! Please let me know of anything you need for Windows PowerShell in the comments below that can help you achieve your goals! I have 18+ years of experience in IT and you can check my Microsoft credentials. Transcript ID: 750479 and Access Code: DejanMladenovic
Credentials About Me...

Recent Posts