Powershell: Get-Help does not work for script files containing using statements.

[hubuk]

Steps to reproduce

Create a script file test.ps1 with the following content:

using namespace System.Management.Automation

<#
.SYNOPSIS
A simple script for problem reproduction.
#>
Param ($SampleParam)

Execute following command:

> Get-Help .\test.ps1

Expected behavior

Get-Help .\test.ps1

NAME
    ...\test.ps1

SYNOPSIS
    A simple script for problem reproduction.


SYNTAX
    ...\test.ps1 [[-SampleParam] <Object>] [<CommonParameters>]


DESCRIPTION


RELATED LINKS

REMARKS
    To see the examples, type: "Get-Help ...\test.ps1 -Examples"
    For more information, type: "Get-Help ...\test.ps1 -Detailed"
    For technical information, type: "Get-Help ...\test.ps1 -Full"

Actual behavior

> Get-Help .\test.ps1
test.ps1 [[-SampleParam] <Object>]

Environment data

Name                           Value
----                           -----
PSVersion                      7.1.0-preview.7
PSEdition                      Core
GitCommitId                    7.1.0-preview.7-10-g3effa204103460c996a8612aa70718fdf924047d
OS                             Microsoft Windows 10.0.18363
Platform                       Win32NT
PSCompatibleVersions           {1.0, 2.0, 3.0, 4.0…}
PSRemotingProtocolVersion      2.3
SerializationVersion           1.1.0.1
WSManStackVersion              3.0

[hubuk]

PR pending.

[jhoneill]

Comment based help must be the first or last thing in the file or in the block for a function, so it comes before the using statement

<#
.SYNOPSIS
A simple script for problem reproduction.
#>
using namespace System.Management.Automation
Param ($SampleParam)
[enum]::GetNames([actionPreference])

Works.

function test-this {
[alias("Test")]
<#
.SYNOPSIS
A simple script for problem reproduction.
#>
Param ($SampleParam)
}

Gives no help

function test-this {
<#
.SYNOPSIS
A simple script for problem reproduction.
#>
[alias("Test")]
Param ($SampleParam)
}

Works.

I would be careful with a change like this which will enable some behavior in new versions but neither works nor errors/warns in old ones.
It seems logical to say those things should be allowed in any order. However when someone takes a script with an order which works in 7.1 and tries to run it on an earlier version they will go crazy trying to figure out why it doesn't work in Windows PowerShell or in something with PowerShell 7.0.2 embedded (like .NET interactive) .

The rules that using can be preceded by comments, and comment based help must be first or last have been there since the features were introduced.

[hubuk]

@jhoneill You are completely right. I got an impression that putting using directives after script documentation is a syntax error. It might be long long time ago when the VSCode tools were not stable enough. Now it works just fine. Thanks for the guidance.
Closing issue and PR.

[doctordns]

I wish that Help was more intelligent - and gave an error when it fails rather than no output.

[vexx32]

Help is mainly parsing comments there; it doesn't see comments where it expects to, so it gives you back the standard result when no CBH is available, just a syntax diagram and some metadata.

It's difficult / impossible for it to distinguish without taking potentially quite a bit of additional time to examine every comment in the file to determine if it _might_ have been intended to be CBH.

The most I'd expect to see is maybe a small comment noting "no comment based help or external help files for this script/function could be found" in the resulting help output.

[doctordns]

I know what it's doing! But if I make a tiny mistake (eg I type a key wronglyl) it just silently fails with no clue where the error is. I just can't always see the error without a few hints

Can Get-Help's comment parser do something to say where it stopped recognising the block comment?? And to avoid issues, Could -Debug to at least show how far in parsing the text it got?