'<#' does not trigger insert of comment based help ('##' does)

[csandfeld]

System Details

- Operating system name and version: Windows 10 Enterprise Version 1709 (OS Build 16299.309)
- VS Code version: 1.21.1
- PowerShell extension version: 1.6.0.0
- Output from `$PSVersionTable`:
PSVersion                      5.1.16299.251
PSEdition                      Desktop
PSCompatibleVersions           {1.0, 2.0, 3.0, 4.0...}
BuildVersion                   10.0.16299.251
CLRVersion                     4.0.30319.42000
WSManStackVersion              3.0
PSRemotingProtocolVersion      2.3
SerializationVersion           1.1.0.1

Issue Description

Typing <# right above/below a function statement, no longer triggers insert of comment based help. Typing ## does work, but I like the block comment better for the comment based help.

See GIF for details:

Attached Logs

vscode-ps-logs.zip

[rkeithhill]

This happens to me at times but usually I'm glad it fails because most of those times I'm commenting out a function and the auto-expansion to a help template is really bothersome.

[Cirzen]

Keith makes a good point. I love the ability to auto insert the help comments, especially with the parameter names already filled out.
I'm not keen on the hash marker on every line though, I think it's uglier than the multi-line comment alternative, and it gets annoying having to insert '#' and set the indent correctly. Would an alternate snippet shortcut be better?

[GABeech]

In addition to the '#' style being uglier the recommended style is to use '<#' block comments.

[TylerLeonhardt]

So it seems that this a pretty opinionated feature. However, we have some conflicting experiences.

• If we allow <# to create block comments, then we hurt those that want to comment out functions.
• If we don't have snippet to create block comments, then we hurt those that like that style of help.

Based on this, I wonder if I can convince those that want a block comment snippet if we can change the trigger from <# to something else like block help, help, <##, or something else... and we add new docs to say how to add new user snippets that would allow you to set <# if you so choose.

That way, both parties have their experience.

Thoughts?

[Cirzen]

Happy with any particular shortcut.
"help" is already an alias though, so my instinct would be to shy away from that. I quite like <##
The comment based help is equally applicable for entire ".ps1" files as well as functions, so I would add the request that it should work for both.

[GABeech]

@tylerl0706 any reason to not make it a config option?

Could be as simple as "powershell.autoGenerateHelp": "off|block|comment|on"

off= don't generate
block = block style ('<# #>')
comment = comment style ('##')
on = enable both.

Default it to on, and people can tweak the config to suit their needs and wants.

[SeeminglyScience]

Slightly more ambiguous solution:

Make the completion provider API available from PowerShell/C# (like was done with code lens and symbols). Then refactor the existing HelpCompletionProvider to implement that API and allow it to be removed/adjusted from PowerShell.

[brettmillerb]

I think the issue here is that the last update broke the way that it worked and typing <# used to generate the help but it doesn't work anymore.

The preferences are also a good discussion but something broke in the last update.

[TylerLeonhardt]

@SeeminglyScience oh I see this is not just a snippet. Got it. Then you're right, completion provider should be available from PowerShell/C#. That way we can also do Register-EditorCompletion or something.

Btw everyone, there is a snippet for <# help called: comment-help!
https://github.com/PowerShell/vscode-powershell/blob/master/snippets/PowerShell.json#L557-L577

Please use that as a work around until this issue is fixed!

[brettmillerb]

The <# used to generate help and include help for already declared parameters. Was awfully handy 👍

[csandfeld]

Exactly @brettmillerb - it used to work when then typing <# but no longer does (I should have been more clear about that when opening the issue).

And as you mentioned above, it was more handy than a regular snippet, as it generated help for already declared parameters - something the snippet does not.

Looking at HelpCompletion.ts it still appear to be setup as a trigger, but for whatever reason it does not work in the latest version.

[GABeech]

After Doing a bit of digging. It seems like the following is happening:

when you type <# it auto-completes to <##> (no space, not sure if this is relevant),

Taking a peek at what is happening in the onEvent function in HelpCompletion.ts, this auto complete is showing up as two text changes:

1: <
2: ##>

This causes the matcher to not match and thus not insert the generated help.

[TylerLeonhardt]

Great find @GABeech!