PowerShell not reading comment-based help section correctly - Stack Overflow

I'm having a really weird problem with help in my module. (this is the third one I'm building and the first time I'm seeing this.)

Pertinent section:

Having a weird comment-based help issue in a module i’m building. Currently, the help looks like:

#!/usr/bin/env pwsh

<#
.DESCRIPTION
This script is a bridge between PowerShell and the AppleScript Choose File UI primitive. It allows the use of the standard macOS Choose File dialog inside a PowerShell script and returns a string array of POSIX-Compliant file paths.
#>

<rest of module>

But when I run Get-Help on it, it says it can’t find the help. I’m at a real loss here.

This is current PowerShell running on macOS, and the other two modules i've done, I've never seen this issue before.

I'm having a really weird problem with help in my module. (this is the third one I'm building and the first time I'm seeing this.)

Pertinent section:

Having a weird comment-based help issue in a module i’m building. Currently, the help looks like:

#!/usr/bin/env pwsh

<#
.DESCRIPTION
This script is a bridge between PowerShell and the AppleScript Choose File UI primitive. It allows the use of the standard macOS Choose File dialog inside a PowerShell script and returns a string array of POSIX-Compliant file paths.
#>

<rest of module>

But when I run Get-Help on it, it says it can’t find the help. I’m at a real loss here.

This is current PowerShell running on macOS, and the other two modules i've done, I've never seen this issue before.

• powershell

Share Improve this question Follow asked Jan 5 at 0:16 user18176479user18176479 7

• A PowerShell module doesn't usually publish shebang line-based shell scripts. The latter would have to be placed in a dir. listed in $env:PATH, which isn't what modules do. If your script is a(n executable) shell script discoverable via $env:PATH, the comment-based help should work; if it isn't, targeting it by its path should work. Please edit your question to clarify your scenario. – mklement0 Commented Jan 5 at 2:54
• All my other modules have that, it’s a help on !windows. The way I’ve implemented this is how I’ve done it for my other modules, github.com/johncwelch/Get-PSDisplayDialog/tree/main/… is the one I released prior to this one, and github.com/johncwelch/Get-PSChooseFile/tree/main/Get-ChooseFile is the problem child. Given my earlier module, I doubt the shebang is the issue. In any event, removing it didn’t fix the problem. – user18176479 Commented Jan 5 at 4:16
• I see. There is indeed no reason to include a shebang line in a .psm1 file, ever. And, indeed, the presence or absence of a shebang line is irrelevant in this context. More importantly, you shouldn't expect comment-based help in the top-level scope - as opposed to in the context of functions exported from this module - in such a file to be honored. Please explain why you do have this expectation. – mklement0 Commented Jan 5 at 4:27
• Well, because it's worked in the past with two other modules, but I think i may have figured out what caused this. In my past modules, the only "function" i had was the "main" or exported one. In this case, the first function is actually called by the exported function, and I think that was causing my problem. I redid the help in this case to be function-based and now it's working. – user18176479 Commented Jan 5 at 4:49
• I'm unclear on what you're trying to say, but, if you think you've found a solution, I encourage you to post it as an answer, along with additional information for clarification. – mklement0 Commented Jan 5 at 5:27

 |  Show 2 more comments

1 Answer 1

Sorted by: Reset to default 2

As stated in the helpful comments from mklement0:

• The shebang line is irrelevant in this context
• Comment-based help doesn't apply to a module but to function (aka command) exported by the module

The comment base help might be either prior the concerned function:

Remove-Module Get-DisplayDialog -ErrorAction SilentlyContinue
{
<#
.DESCRIPTION
This script is a bridge between PowerShell and the AppleScript Choose File UI primitive. It allows the use of the standard macOS Choose File dialog inside a PowerShell script and returns a string array of POSIX-Compliant file paths.
#>
function Get-DisplayDialog { }
Export-ModuleMember -Function Get-DisplayDialog
} | Set-Content -Path .\Get-DisplayDialog.psm1
Import-Module .\Get-DisplayDialog.psm1

or embedded in the the top of the function:

Remove-Module Get-DisplayDialog -ErrorAction SilentlyContinue
{
function Get-DisplayDialog {
<#
.DESCRIPTION
This script is a bridge between PowerShell and the AppleScript Choose File UI primitive. It allows the use of the standard macOS Choose File dialog inside a PowerShell script and returns a string array of POSIX-Compliant file paths.
#>
}
Export-ModuleMember -Function Get-DisplayDialog
} | Set-Content -Path .\Get-DisplayDialog.psm1
Import-Module .\Get-DisplayDialog.psm1

After pasting either of the examples above into a PowerShell host or terminal, you might get the help of the specific exported function:

Get-Help Get-DisplayDialog

NAME
    Get-DisplayDialog
    
SYNOPSIS
    
    
SYNTAX
    Get-DisplayDialog [<CommonParameters>]


DESCRIPTION
    This script is a bridge between PowerShell and the AppleScript Choose File UI primitive. It allows the use of the standard macOS Choose File dialog     
    inside a PowerShell script and returns a string array of POSIX-Compliant file paths.

...

There are two pitfalls to mention here that might have lead to some confusion:

• If the module is already imported and loaded, you will need to remove it (Remove-Module Get-DisplayDialog -ErrorAction SilentlyContinue) or open a new PowerShell session in order to see the new result.

• Your exported function has the same name as the module (Get-DisplayDialog), there is nothing wrong with that, but to be clear: you aren't retrieving the help of the module but the help of the exported function(s).