powershellsyntaxhelp-system

Powershell Comment-Based Help for scripts

I'm unable to access Comment-Based Help in my script.

The command I'm using is this:

PS C:\MyDir> Get-Help .\do-something.ps1 -Full (do-something.ps1 is in MyDir).

My question is:

Should I expect this command to work the same in the ISE Console Pane as well as the PS Console?

I've reviewed the Microsoft Documentation and distilled the following. Have I missed anything? Are there any scenarios where Comment-Based Help simply does not work?

PowerShell will NOT parse Comment-Based help for a script unless:

  1. The Comment-Based Help section begins on the first line of the script, or is preceded only by blank lines.

  2. There are at least two blank lines after the Comment-Based Help section if it's followed by a Function declaration.

  3. The script file is in a directory that is in $env:PATH. You must use -Path parmeter if it is not in $env:Path.

  4. Only valid Comment-Based Help keywords are used. If you misspell one, the Get-Help command will fail silently without any error.

  5. The Get-Help command uses correct syntax, for example:

PS C:\MyDir> Get-Help .\do-something.ps1 -Full

  1. The Comment-Based Help section is formatted properly, for example:

Positioned at top of script file:

<#
.SYNOPSIS
Does something.

.DESCRIPTION
Performs tasks and produces output.
#>
Solution

  • Should I expect this command to work the same in the ISE Console Pane as well as the PS Console?

    Yes. Comment-based help is parsed by PowerShell (system.management.automation.dll), not the host.

    Are there any scenarios where Comment-Based Help simply does not work?

    Comment-based help only works if the script can be executed. If the execution policy or application control like AppLocker prohibits the execution of the script, or if you have a syntax error in the script, Get-Help cannot display the comment-based help.