1

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.
#>
mklement0
  • 382,024
  • 64
  • 607
  • 775
jott19
  • 371
  • 3
  • 13
  • if it works in powershell.exe, then it almost always works in the ISE. the other direction has a larger chance of failure. [*grin*] can you post a working code sample? the ISE may be parsing more rigidly ... – Lee_Dailey Nov 23 '18 at 20:35
  • 1
    Perhaps I'm not using the command properly? I've issued the command just as described in my post. The output I receive is what you would get if you just issued the command `Get-Help` without any arguments. – jott19 Nov 23 '18 at 23:45
  • without code to check, there is no way to determine the cause of the glitch. it SHOULD work the same in both the standard ISE console and the standard powershell.exe console. there are other consoles, tho ... – Lee_Dailey Nov 23 '18 at 23:50

1 Answers1

1

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.

mklement0
  • 382,024
  • 64
  • 607
  • 775
vrdse
  • 2,899
  • 10
  • 20
  • I do have `Set-StrictMode -Version 2.0` set in the script - there may be some variables that cannot be set due to unavailability of files used for processing. Or perhaps a loaded module it causing it to fail? I will do more testing... – jott19 Nov 23 '18 at 23:57
  • The problem was the script was not executable. This was the one item I omitted in the list of requirements posted in my original question. – jott19 Nov 24 '18 at 18:49