Summary: Automatically add comment-based help to your Windows PowerShell scripts; learn how in this how-to article by Scripting Guy Ed Wilson.

Microsoft Scripting Guy Ed Wilson here. Last Sunday, I spent the morning creating a Windows PowerShell ISE profile. Today, I thought I would add something to that profile that will make my life easier. When I was creating the conversion module back in the series of articles I wrote about creating and using modules, I created a text file that I called my help template. When I wish to add comment-based help to a script or to a function, I have to do the following:

1. Use search to locate the help text file.
2. Open the help text file in Notepad.
3. Copy the text of the file to the clipboard.
4. Switch to the Windows PowerShell ISE.
5. Paste the contents of the clipboard to the script or function that is under development.
6. Switch back to Notepad.
7. Close the help text file.
8. Close the Windows Search results Explorer pane.
9. Switch back to the Windows PowerShell ISE.
10. Edit the comment-based text in the Windows PowerShell ISE.
11. Add the current date to the last edit field of the comment.

Granted, it does not take a long time to perform these 11 steps, but it is a lot of mousing and typing, and it does take several minutes to complete. As a result, I do not add comment-based help to my scripts or functions as often as I should.

Now that I have a Windows PowerShell ISE profile, it makes sense to add a function to automatically add comment-based help to my Windows PowerShell scripts and functions. The function is called Add-Help and is shown here.

Add-Help

Function Add-Help
{
 $helpText = @”
<#
   .Synopsis
    This does that 
   .Example
    Example-
    Example- accomplishes 
   .Parameter 
    The parameter
   .Notes
    NAME: Example-
    AUTHOR: $env:username
    LASTEDIT: $(Get-Date)
    KEYWORDS:
   .Link
    Http://www.ScriptingGuys.com
#Requires -Version 2.0
#>
“@
 $psise.CurrentFile.Editor.InsertText($helpText)
} #end function add-help

The first thing I do in the Add-Help function is create a here-string. The here-string allows me to not worry about quoting rules or other coding conventions. Everything between the @” and the “@ symbols is interpreted as a string. Just as there are two kinds of regular strings—literal and expanding—so too are there two kinds of here-strings, literal and expanding. I am using the expanding here-string so that I can get the date to update. In addition, the username is pulled from the environmental username variable. If you do not want to use the environmental username variable for your script user name, you can hard code this value (this is in fact what I do in my personal Windows PowerShell ISE profile).

Beyond the expanding here-string, the only really interesting thing about the function is the line of code that inserts text (obviously, this takes place at the current insertion point). To do this, I use the InsertText method from the Editor object from the CurrentFile object. This code is shown here:

$psise.CurrentFile.Editor.InsertText($helpText)

To add the Add-Help function to my Windows PowerShell ISE profile, I use the Set-Profile function I created last Sunday. It opens my profile in the Windows PowerShell ISE. Next I simply paste the function in the profile as shown in the following image.

After I have saved the Windows PowerShell ISE profile, and closed and reopened the Windows PowerShell ISE. I now place my insertion point to the first line under the opening brace (curly bracket) of the Add-Help function, and I use the Add-Help function to add help to my Add-Help function. This is shown in the following image.

One thing to keep in mind is that by default, my Add-Help function adds the .Parameter comment. If you do not have any parameters, or if you do not use this comment properly, your help will not work with the Get-Help cmdlet. If you do not intend to use this comment, delete it before adding the Add-Help function to your profile.

We invite you to follow us on Twitter and Facebook. If you have any questions, send email to us at scripter@microsoft.com, or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.

Ed Wilson and Craig Liebendorfer, Scripting Guys