Close

PowerShell Comment Based Help: Examples with Multiple Lines of Code

One of the reasons I love PowerShell is the comment based help. This allows you to easily get documentation for functions directly within your PowerShell session. By using Get-Help for a function you can retrieve a description, information on the parameters, and examples of how to use the function.

Recently I was adding help to a function  and wanted to add two lines of code to my example. Usually the syntax for an example looks like this:

.EXAMPLE
Get-Cat
 
This will get me a default of one cat.

The first line under .EXAMPLE will be formatted with a PowerShell prompt in front to show it is code. The second line is a description of the example.

If I want to add two lines of code, and I used the following, it would only display the first line with a prompt as shown in the screenshot below.

.EXAMPLE
$cats = 4
Get-Cat -NumberOfCats $cats
 
Store the number of cats in a variable and then get that number of cats.

You can see above the first example looks good, however in the second example the first two lines should both have a prompt to show they are code. I spent a little while Googling this without much avail. I then figured, somewhere within dbatools there must be an example with two lines of code. Sure enough I found my answer, and it’s pretty straightforward. You just add the prompt to the code yourself and then when the example is displayed it is formatted properly.

I changed my examples to the following and you can see now they display as expected.

.EXAMPLE
PS C:\>Get-Cat
 
This will get me a default of one cat.
 
.EXAMPLE
PS C:\>$cats = 4
PS C:\>Get-Cat -NumberOfCats $cats
 
Store the number of cats in a variable and then get that number of cats.

I know you’re all dying to see the result of my Get-Cat function so here you go. If you need to add this to your PowerShell profile etc. so you can quickly brighten any day, the code is on my github.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: