Powershell: shebang interpreter #!/usr/local/bin/pwsh breaks best practise Powershell commenting structure

[sonjz]

On my Mac (OSX 10.13.6), after performing a brew cask install powershell, I proceeded to try create a best practise commenting for test.ps1 and found the shebang pwsh and script comment to conflict.

Steps to reproduce

#!/usr/local/bin/pwsh
<#
    .SYNOPSIS
    test.ps1
    ...
#>

# return usage
get-help "./$($MyInvocation.MyCommand.Name)" -Detailed ;

chmod +x test.ps1 ;
./test.ps1

Expected behavior

Expect to get detailed help back.

Actual behavior

Just get parameter usage. It appears that <# ... #> comment needs to be the first line, just like the shebang pwsh needs to be the first line. Removing either makes the other work.

Why this is bad

Not having the shebang interpreter + standard commenting will slow down ease of use / adoption for *nix users (i.e not having to run pwsh ./test.ps1)

Environment data

Name                           Value
----                           -----
PSVersion                      6.1.0
PSEdition                      Core
GitCommitId                    6.1.0
OS                             Darwin 17.7.0 Darwin Kernel Version 17.7.0: Fri Jul  6 19:54:51 PDT 2018; root:xnu-4570.71.3~2/RELEASE_X86_64
Platform                       Unix
PSCompatibleVersions           {1.0, 2.0, 3.0, 4.0...}
PSRemotingProtocolVersion      2.3
SerializationVersion           1.1.0.1
WSManStackVersion              3.0

[rkeithhill]

You can workaround this for now by inserting a blank line after the shebang. That works for me on Linux.

[sonjz]

Thanks @rkeithhill !

[vexx32]

I don't know if I'd close it just yet @sonjz -- a workaround is great, but ideally it should be fixed so that the extra line isn't necessary. 😄

[SteveL-MSFT]

I agree, the workaround is great, but not easily discoverable.

[SteveL-MSFT]

I take it back, looks like it's explicitly documented that the comment based help block must be standalone (that is newline separated from preceding comments) https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_comment_based_help?view=powershell-6