December 22, 2016 / by June Blender / Best practices, Pester, PowerShell, PowerShell HelpWriter, Puzzle / No Comments

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 2.0.0.0 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.

Like this Friday PowerShell Puzzle? Find more puzzles here. If you have a PowerShell puzzle suggestion, post it here or ping me on Twitter at @juneb_get_help.

June Blender is a technology evangelist at SAPIEN Technologies, Inc. and a Microsoft Cloud & DataCenter MVP. You can reach her at juneb@sapien.com or follow her on Twitter at @juneb_get_help.

RSS SAPIEN Info Center

Search the Archives

Join our mailing list

Enter your email address to subscribe to our mailing lists for Monthly Blog Digests, Product Announcements and more (you can choose which you receive once you sign-up!)

Tags

Categories

Archives

BlogRoll

PowerShell Links

Information

Dashboard