You can add your own comments to your scripts, creating your own online help and tutorial system.
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.
There are a few rules for comment-based help I should cover right up front:
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:
The synopsis goes here. This can be one line, or many.
The description is usually a longer, more detailed explanation of what the script or function does. Take as many lines as you need.
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:
Provide a PARAMETER section for each parameter that your script or function accepts.
There's no need to number your examples.
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 http:// 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.
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 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.