Nigel Boulton's Blog
7May/1125

Problems with PowerShell Comment-based Help

I was writing a script recently and came across a couple of "gotchas" when attempting to use PowerShell 2's Comment-based Help at script level. A simple test script to demonstrate what I am about to describe is shown below:

<#
.SYNOPSIS
    Tests whether PowerShell 2 Comment-based Help is working as expected
.DESCRIPTION
    Displays Comment-based Help for this script
.EXAMPLE
    Test-CommentBasedHelp.ps1
.NOTES
    None
#>            
Write-Host "Hello World"


The expected output from this is as follows:

Expected output from test script showing Comment-based Help working

"Get-Help about_comment_based_help" says

"SYNTAX FOR COMMENT-BASED HELP IN SCRIPTS

  Comment-based Help for a script can appear in one of the following two

  locations in the script.

  -- At the beginning of the script file. Script Help can be preceded in the 
     script only by comments and blank lines.

  -- If the first item in the script body (after the Help) is a function 
     declaration, there must be at least two blank lines between the end of the 
     script Help and the function declaration. Otherwise, the Help is 
     interpreted as being Help for the function, not Help for the script.

  -- At the end of the script file."

Looks straightforward enough. However, if you try the following:

# Comment            
<#
.SYNOPSIS
    Tests whether PowerShell 2 Comment-based Help is working as expected
.DESCRIPTION
    Displays Comment-based Help for this script
.EXAMPLE
    Test-CommentBasedHelp.ps1
.NOTES
    None
#>            
Write-Host "Hello World"

The output isn't as expected. You just get the name of the script returned, as shown below:

Output from test script showing just script name returned

What's that about…? Well, this is the first "gotcha". Although Get-Help says that Script Help can be preceded in the script by comments and blank lines, it's easy to miss the text further up that says

"All of the lines in a comment-based Help topic must be contiguous. If a comment-based Help topic follows a comment that is not part of the Help topic, there must be at least one blank line between the last non-Help comment line and the beginning of the comment-based Help."

So to avoid breaking it, you need to use the following syntax:

# Comment            

<#
.SYNOPSIS
    Tests whether PowerShell 2 Comment-based Help is working as expected
.DESCRIPTION
    Displays Comment-based Help for this script
.EXAMPLE
    Test-CommentBasedHelp.ps1
.NOTES
    None
#>            
Write-Host "Hello World"

One tiny blank line can make such a difference!

The same applies if you put anything inside the comment block before the first keyword. For example, the following is not valid:

<#
Comment
.SYNOPSIS
    Tests whether PowerShell 2 Comment-based Help is working as expected
.DESCRIPTION
    Displays Comment-based Help for this script
.EXAMPLE
    Test-CommentBasedHelp.ps1
.NOTES
    None
#>            
Write-Host "Hello World"


The second "gotcha" is around the fact that Get-Help says that "at the end of the script file" is a valid location for Comment-based Help for a script. This is true, but if you do this, be aware of the fact that if you subsequently sign your script, a signature block is added to the end of the script which means that your Comment-Based Help block is no longer at the end of the file, and you will get the symptom described above.

Write-Host "Hello World"            
<#
.SYNOPSIS
    Tests whether PowerShell 2 Comment-based Help is working as expected
.DESCRIPTION
    Displays Comment-based Help for this script
.EXAMPLE
    Test-CommentBasedHelp.ps1
.NOTES
    None
#>            

# SIG # Begin signature block            
# MIID/wYJKddoZIhvcNAQcCoIID8DCCA+wCAQExCzAJBgUrDgMCGgUAMGkGCisGAQ            
# gjcWqCA56QSgWzBZMDQGCisGAQQBgjcCAR4wJgIDAQAABBAfzDtgWUsITrck0sYp            
# AgEAAgEAAgEAAgEAAgEAMCEwCQYFKw4DAhoFAAQUXPsShpFvys7oIWj23R6GpiQb            
# l46gggIdMIICGTCCAYKgAwIBAgIQSqeTRu71Hp1OJu+xx6ASfzANBgkqhkiG9w0B            
# AQQFADAYMRYwFAYDVQQDEw1OaWdlbCBCd5b3VsdG9uMCAXDTAwMDEwMTAwMDAwMF            
# DzIwOTkwMTAxMDAwMDAwWjAYMRYwFA68YDVQQDEw1OaWdlbCBCb3VsdG9uMIGfMA            
# CSqGSIb3DQEBAQPd789yhiCBiQKBgQC0+WAMn64J4oKsTIKsbBH5cTB4fEnfafzG            
# 1G+QkkgHpimfbT0Y+XrfmqKP6G/ailX3BHvwYOMmuSARqutfF6Rv9AQ7B/Sl8BgH            
# +AztcWg+jNko9dTidqexjH+bunpbzFMIJ6Lnzr+xSBvAbQR8oWtOwodQASW0G4Ra            
# b7+u5VZBaQIDAQABo2IwYDATBgNVHSUEDDAKBggrBgEFBQcDAzBJBgNVHQEEQjBA            
# gBCJKelkj8xj96uouh6cXclzoRowGDEWMBQGA1UEAxMNTmlnZWwgQm91bHRvboIQ            
# SqeTRu71Hp1OJu+xx6ASfzAHJy578}iG9w0BAQQFAAOBgQBw/WwbWGAHyyGjDhpb            
# Z7i8duiLHBBRYfUpczIh02jXPU+DfWa7atfwuFyxeilUDTszZ/2dOplH8l394j3H            
# yy8ZqXTf796zLqWXmvZn85rkgm16rRXqzDBheHidyTP3cPRPn7ehCahAAqpmHS0y            
# H7X3bevXIvMwDSXpL47nCCfWUDGCAUwwggFIAgEBMCwwGDEWMBQv0GA1UEAxMNTm            
# ZWwgQm91bHRvbgIQSqeTRu71Hp1OJu+xx6ASfzAJBgUrDgMCGgUAoHgwGAYKKwYB            
# BAGCNwIBDDEKMAhjY7guigAoAAoQKAADAZBgkqhkiG9w0BCQMxDAYKKwYBBAGCNw            
# BgorBgEEAYI3ACBgELMQ4wDAYKKwYBBAGCNwIBFTAjBgkqhkiG9w0BCQQxFgQULr            
# hd1Ib4bCuTXkm35KwTLDIiK58wDQYJKoZIcxhvcNAQEBBQAEgYCPumseo6AGAZFD            
# R37Tj8Kx6E0E6+MHqMHZ1TcLjO3E/lZqzFW7cCTJOcIH6Yg78r2DiToGXISdJkk8            
# 9sBB3nbsvQHWsWOYdRVwH8VueRg9paSa3CMj87E500z6bElejYGOi9VVfDZ8xBwm            
# rY4aAWd5A2dDpnojJQLC1yCv8w==            
# SIG # End signature block

Update: Please see the comment below from June Blender at Microsoft, who writes PowerShell Help. She has kindly updated the PowerShell Online Help topic about_Comment_Based_Help (available here) to reflect this "gotcha". Some further good news is that this change made it into the Windows PowerShell 2.0 Core Help May 2011 Update, which provides updated PowerShell Help in a CHM format (handy for searching!).

Hope this information is useful to you, I spent more time than I would have liked chasing this around!

Filed under: PowerShell 25 Comments