{"id":8804,"date":"2015-02-18T06:00:00","date_gmt":"2015-02-18T14:00:00","guid":{"rendered":"http:\/\/www.sapien.com\/blog\/?p=8804"},"modified":"2016-04-25T07:41:06","modified_gmt":"2016-04-25T14:41:06","slug":"troubleshooting-comment-based-help","status":"publish","type":"post","link":"https:\/\/dev.sapien.com\/blog\/2015\/02\/18\/troubleshooting-comment-based-help\/","title":{"rendered":"Troubleshooting Comment-Based Help"},"content":{"rendered":"

Follow @juneb_get_help<\/a><\/p>\n

A Windows PowerShell user group member recently came to me with a question about comment-based help in Windows PowerShell. It reminded me again that comment-based help is not as easy to use as you might think. Here are a few tips to help you avoid and fix obvious pitfalls.<\/p>\n

TIP: When testing help, be sure to restart your session between each test. Windows PowerShell caches help for the session, so changes to the help are effective only in a new session.<\/p>\n

 <\/p>\n

\"image\"<\/a><\/p>\n

 <\/p>\n

RTFM: about_Comment_Based_Help<\/h2>\n

The best way to avoid errors is to read the about_Comment_Based_Help<\/a> topic. It covers issues like the placement of comment-based help in functions, scripts, and script modules. It lists the keywords and provides some useful examples. Be sure to start there. This post is supplemental.<\/p>\n

 <\/p>\n

Use Only Valid Keywords<\/h2>\n

Comment-based help must include only valid keywords. If even one keyword is invalid, Get-Help ignores the entire comment-based help block and displays auto-generated help.<\/p>\n

The keyword names are case-insensitive, but they must be spelled exactly as specified. The dot and the keyword name cannot be separated by even one space. None of the keywords are required* in comment-based help, but you can’t add or change keywords, even it you really want a new one (such as .FILENAME, which would be a really good idea). If you use .NOTE (instead of .NOTES) or .EXAMPLES (instead of .EXAMPLE), Get-Help doesn’t display any of it.<\/p>\n

It’s very picky! If the format of a keyword is wrong, such as forgetting to place the parameter name on the same line as the .PARAMETER keyword, the entire comment-based help block is ignored.<\/p>\n

.SYNOPSIS\r\n.DESCRIPTION\r\n.PARAMETER\r\n.EXAMPLE\r\n.INPUTS\r\n.OUTPUTS\r\n.NOTES\r\n.LINK\r\n.COMPONENT\r\n.ROLE\r\n.FUNCTIONALITY\r\n.FORWARDHELPTARGETNAME\r\n.FORWARDHELPCATEGORY\r\n.REMOTEHELPRUNSPACE\r\n.EXTERNALHELP<\/pre>\n
*.ExternalHelp is required for function with Help XML files, but it’s not required for the comment-based help display.<\/p>\n
Also, for function help placed immediately before the function, you can have no more than one line blank line between the end the help block and the line on which the function is defined. If there are two blank lines, Get-Help associates the help with the script or module file, not the function.<\/p>\n
This is valid function help.<\/p>\n
\r\n<#\r\n .DESCRIPTION\r\n Nice function\r\n#>\r\nfunction Get-NiceFunction {}<\/pre>\n
This is valid function help.<\/p>\n
\r\n<#\r\n .DESCRIPTION\r\n Nice function\r\n\r\n#>\r\nfunction Get-NiceFunction {}<\/pre>\n
This doesn’t work. Get-Help displays auto-generated help for the function. It associates the help comments with the script, not the function.<\/p>\n
\r\n<#\r\n .DESCRIPTION\r\n Nice function\r\n#>\r\n\r\n\r\nfunction Get-NiceFunction {}<\/pre>\n
 <\/p>\n
Distinguish HelpMessage from Parameter Comments and .PARAMETER<\/h2>\n
There are three ways to add a parameter description to function help. I’ve listed them below in precedence order.<\/p>\n
Notice that Get-Help displays a parameter comment<\/strong> only when there is at least one valid comment-based help keyword for the command and it is not a .PARAMETER keyword for the same parameter. If the parameter comment is the only help for the command, it is ignored.<\/p>\n
Also, the HelpMessage attribute is part of auto-generated help, not comment-based help.<\/p>\n
 <\/p>\n