Friday Puzzle: Phantom Help
On Friday, December 16, 2016, I posted the following puzzle on Twitter.
It shows a function that has no comment-based help or XML help, but when you run Get-Help on the function, Get-Help displays both a description and notes for the function.
What is the source of help for this function? I call this unintentional help “phantom help.”
The Solution: Missing Blank Lines
The answer is that Get-Help is getting help for the script or module that contains the function and displaying it as function help.
When the script or module has help, or anything that might be interpreted as help, there must be at least two blank lines between the end of the help block and the Function keyword.
When there’s fewer than two blank lines, Get-Help interprets any help as help for the function. If we were to zoom out from the puzzle image, here’s what you’d see in the Get-CultureDate.ps1 script.
The script has the beginnings of help — just a to-do list — and just one blank line between the script help and the Function keyword for the Get-CultureDate function.
When you dot-source the script and run Get-Help on the function, Get-Help displays the script help as the function help.
This happens surprisingly often and is the source of much angst among people writing help.
Hiding XML Help
There’s an even more frustrating version of this problem. The author writes a nice module with well-written XML help.
Then, the author makes just a few minor changes to the module (represented here by version 126.96.36.199 of the same module) and, suddenly, even though the unchanged XML help file is still there, the XML help for the function is gone!
Here’s the culprit. Just one line between some formatted module notes and the Function keyword.
Because comment-based help takes precedence over XML help (except for the .ExternalHelp keyword, which has the highest precedence order), the notes for the module are interpreted as function help, and they override the help in the XML help file.
Real Solution: Test Your Help
The reliable solution to the puzzle is to test your help. I have several Pester tests that test help on GitHub. Just grab them and run them routinely.
If your tests fail or strange things are appearing where help should be, verify that you have two blank lines before the function or before its comment-based help.
June Blender is a technology evangelist at SAPIEN Technologies, Inc. and a Microsoft Cloud & DataCenter MVP. You can reach her at firstname.lastname@example.org or follow her on Twitter at @juneb_get_help.