Powershell: Comment based help does not work for scripts that start with a shebang

Created on 16 Nov 2017  ·  3Comments  ·  Source: PowerShell/PowerShell

PowerShell does not parse comment based help for a script unless the help comment starts on the first line of the script. This prevents scripts employing a shebang from being helpful via Get-Help.

PowerShell should skip the first line of a script file if it starts with #!.

Steps to reproduce

Create a new script called thing.ps1 with a shebang:

#!/usr/bin/env pwsh
<#
.SYNOPSIS
This does a thing
#>

Expected behavior

PS> Get-Help thing.ps1

NAME
    /Users/aaron/src/thing.ps1

SYNOPSIS
    This does a thing

…

Actual behavior

PS> Get-Help thing.ps1
thing.ps1
…

Environment data

PS> $PSVersionTable

Name                           Value
----                           -----
PSVersion                      6.0.0-beta.9
PSEdition                      Core
GitCommitId                    v6.0.0-beta.9
OS                             Darwin 16.7.0 Darwin Kernel Version 16.7.0: Thu Jun 15 17:36:27 PDT 2017; root:xnu...
Platform                       Unix
PSCompatibleVersions           {1.0, 2.0, 3.0, 4.0...}
PSRemotingProtocolVersion      2.3
SerializationVersion           1.1.0.1
WSManStackVersion              3.0
Issue-Enhancement WG-Interactive-HelpSystem

Most helpful comment

This is definitely a bug. However ...

You just need a blank line between the shebang and the help to work around it.

All 3 comments

Note, this is an issue with both syntaxes:

#!/usr/bin/env pwsh
# .SYNOPSIS
# This does a thing

This is definitely a bug. However ...

You just need a blank line between the shebang and the help to work around it.

Is this because contiguous spans of comments are all grouped together, so the help system considers the shebang and the synopsis to be the same comment?

Was this page helpful?
0 / 5 - 0 ratings