Windows PowerShell: Comment your way to help

  • Article

You can add your own comments to your scripts, creating your own online help and tutorial system.

Don Jones

One of the neatest things about Windows PowerShell is its help system. The help files include syntax overviews, detailed explanations, examples and so on.

Given that a command-line shell can’t offer discoverability features such as context menus, toolbars, ribbons and so forth, the help file stands on its own as a discoverability feature. You can use it with wildcards, for example, to discover new commands. Then you can read their help to learn how to use them.

As you produce your own commands as functions and scripts, you’d do well to keep your work as polished as the native Windows PowerShell cmdlets. You should always endeavor to make your work as consistent as possible with the rest of the shell. Part of that consistency and polish is in how you prepare and provide help.

You could produce the exact same kind of XML-based help files that Windows PowerShell itself uses. There’s more discussion on this topic in my self-published book, “Windows PowerShell Scripting and Toolmaking.” However, most of you won’t need the flexibility those help files offer, such as the ability to provide help in multiple languages.

You can take a much easier route. You can simply use comment-based help.

Comment-based help rules

There are a few rules for comment-based help I should cover right up front:

  • Generally, you’ll want to enclose your special comment blocks in the <# block comment #> markers. It’s also legal to simply comment every line by starting it with the # comment character.
  • Comment-based help should be the first thing in the script file. It’s preferable to include the help within the function rather than just before. That helps keep the comment “part” of the function, and ensures Windows PowerShell won’t confuse it for something else. It’s also legal to put the script’s comment-based help at the end of the file, but I dislike doing that because it diminishes some of the other benefits of using comment-based help.
  • If you’re providing help for a function, the comment-based help block can come immediately before or immediately after the function name and opening curly bracket.
  • When you put multiple functions into a script, such as a script module, you can provide help for the file by putting the comment block at the top. Make sure to add at least a few blank lines after that comment block, so that any subsequent function-specific help will stand apart properly.
  • If you misspell any of the comment-based help keywords, Windows PowerShell might just ignore the entire block. So be careful of your spelling, because it counts.

Comment-based help syntax

Comment-based help consists of one or more sections. Each section starts with a dotted keyword, followed by one or more lines of text. For example:

<#
.SYNOPSIS

The synopsis goes here. This can be one line, or many.
.DESCRIPTION

The description is usually a longer, more detailed explanation of what the script or function does. Take as many lines as you need.
.PARAMETER computername

Here, the dotted keyword is followed by a single parameter name. Don't precede that with a hyphen. The following lines describe the purpose of the parameter:
.PARAMETER filePath

Provide a PARAMETER section for each parameter that your script or function accepts.
.EXAMPLE

There's no need to number your examples.
.EXAMPLE
PowerShell will number them for you when it displays your help text to a user.
#>

That example includes the four most-commonly used dotted keywords. You’ll notice these start with a dot or period. Windows PowerShell isn’t case-sensitive about those, although the documentation lists them in all uppercase (so I tend to do the same). Using all uppercase also makes the sections stand out a bit more when you’re reading the code in a script editor.

One other neat section you can use is LINK. With this, you can include a URL, starting with the https:// address, to an online version of your help. Posting your help on an intranet site, for example, lets someone get more detail, possibly more examples, find out how to contact you and so on.

Windows PowerShell auto-generates additional help content by looking at your script or function. It derives the name, the basic syntax (including parameter names and data types) and other information. It does not detect any default values you may have coded in a parameter:

Param($computername = 'localhost')

Therefore, you should take care to document any defaults in the help for the parameter itself, or even in the description.

Comment-based awesomeness

Another advantage of comment-based help is that it provides two kinds of help. One is for folks who run help against your scripts and functions. The other is for someone reading your scripts.

In other words, well-written comment-based help can also double as in-line documentation that you probably prefer to put in any kind of your scripts.

Don Jones

Don Jones is a Microsoft MVP Award recipient and author of “Learn Windows PowerShell in a Month of Lunches” (Manning Publications, 2011), a book designed to help any administrator become effective with Windows PowerShell. Jones also offers public and on-site Windows PowerShell training. Contact him through ConcentratedTech.com or bit.ly/AskDon.

Related Content