Designing Help Documentation for Windows PowerShell Scripts

  • 12/16/2009

Using Multiple-Line Comment Tags in Windows PowerShell 2.0

Windows PowerShell 2.0 introduces multiple-line comment tags that can be used to comment one or more lines in a script. These comment tags work in a similar fashion to here-strings or HTML tags in that, when you open a comment tag, you must also close the comment tag.

Creating Multiple-Line Comments with Comment Tags

The opening tag is the left angle bracket pound sign (<#), and the closing comment tag is the pound sign right angle bracket (#>). The pattern for the use of the multiline comment is shown here.

<# Opening comment tag
First line comment
Additional comment lines
#> Closing comment tag

The use of the multiline comment is seen in the Demo-MultilineComment.ps1 script.

Example 10-7. Demo-MultilineComment.ps1

<#
Get-Command
Get-Help
#>
"The above is a multiline comment"

When the Demo-MultilineComment.ps1 script is run, the two cmdlets shown inside the comment tags are not run; the only command that runs is the one outside of the comment block, which prints a string in the console window. The output from the Demo-MultilineComment.ps1 script is shown here.

The above is a multiline comment

Multiline comment tags do not need to be placed on individual lines. It is perfectly permissible to include the commented text on the line that supplies the comment characters. The pattern for the alternate multiline comment tag placement is shown here.

<# Opening comment tag First line comment
Additional comment lines #> Closing comment tag

The alternate multiline comment tag placement is shown in MultilineDemo2.ps1.

Example 10-8. MultilineDemo2.ps1

<# Get-Help
   Get-Command #>
"The above is a multiline comment"

Creating Single-Line Comments with Comment Tags

You can use the multiline comment syntax to comment a single line of code, with the advantage being that you do not mix your comment characters. You can use a single comment pattern for all of the comments in the script as shown here.

<# Opening comment tag First line comment #> Closing comment tag

An example of the single comment pattern in a script is shown in the MultilineDemo3.ps1 script.

Example 10-9. MultilineDemo3.ps1

<# This is a single comment #>
"The above is a single comment"

When using the multiline comment pattern, it is important to keep in mind that anything placed after the end of the closing comment tag is parsed by Windows PowerShell. Only items placed within the multiline comment characters are commented out. However, multiline commenting behavior is completely different from using the pound sign (#) single-line comment character. It is also a foreign concept to users of VBScript who are used to the behavior of the single quote (') comment character in which anything after the character is commented out. A typical-use scenario that generates an error is illustrated in the following example.

<# -----------------------------
This example causes an error
#> -----------------------------

If you need to highlight your comments in the manner shown in the previous example, you only need to change the position of the last comment tag by moving it to the end of the line to remove the error. The modified comment is shown here.

<# ---------------------------------
This example does not cause an error
----------------------------------- #>

The single pound sign (#) is still accepted for commenting, and there is nothing to prohibit its use. To perform a multiline comment using the single pound sign, you simply place a pound sign in front of each line that requires commenting. This pattern has the advantage of familiarity and consistency of behavior. The fact that it is also backward compatible with Windows PowerShell 1.0 is an added bonus.

# First commented line
# additional commented line
# last commented line