vscode-powershell: '<#' does not trigger insert of comment based help ('##' does)

The code as designed only works with two character triggers.

BTW why does the PowerShell lang config file contain this auto-closing pair:

		["/**", " */"],

WTF? And C# has a bit better auto-closing def that at leasst puts a space in there:

{ "open": "/*", "close": " */", "notIn": ["string"] }

So we should probably use this for PowerShell:

{ "open": "<#", "close": " #>", "notIn": ["string", "comment"] }

The bulk of the help comments I’ve seen and created use Block comment style. I’m really leaning towards a setting and a single trigger seq - ##.

@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!

@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.

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

The only drawback I see from not having <# trigger help completion, is limited discoverability of the feature (I would not have noticed the feature, had it not been for the <# trigger). With that said, I think the ## trigger with an option to configure the style would work well.

Besides the trigger, maybe a “PowerShell: Insert comment based help” option could be added to the command palette? And if possible, also an option to update already generated help (usefull when parameters have changed).

The suggested .INPUT/.OUTPUT additions to the help generation would also be usefull.

Can we not use help-block along the lines of comment-help which already exists or is there a need to distinguish between the two different types of snippet?

There is a difference. The help completion provider understands the AST of the function and creates boiler-plate text for each parameter. That is one (maybe the only) feature that folks really like.

I think I’m going to create a PR with this change - ## is only trigger with a setting to disable this feature or select the comment style (block or line). And then we can see what folks think in the weekly drops.

BTW the help generation could be smarter and take into account [OutputType([type])] to put in the .OUTPUT section. Ditto for reading [Parameter()] attr values for populating .INPUT.

Would it be possible to create a Command Pallet action to trigger the generation of comment-based help. While we’re at it, I would also recommend creating a Settings option for the default location of comment-based help. I’m sure people are very passionate about where the correct place is for that block of text.

If I had a say in the matter, the default should be between the function name and the param block, if only to allow for better code collapsing.

function Test-Function {
<#
  .SYNOPSIS
    Blah
#>
[CmdletBinding()]
param()

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.

Personally, I wish the help generation would only kick in when I really ask for it. I dislike using .PARAMETER in comment-based help, so there’s not much I want generated in help anyway (a little snippet is enough).

I also never want help outside the function…

Maybe it could trigger off a period… but only when it’s as the first non-whitespace, non-comment character, within the first comment block in a script / script block / function… and there’s no param() above it. 🙄

P.S. I definitely think they should have a space on the closing #> as suggested. I don’t mind the auto-closing, but normally I want to type: <# and have insert the #> but then 9 times out of 10 I’m going to hit {Enter} and I want it to indent and insert an extra line break before the closing #> … something like:

<#
    {CursorHere}
#>

Then, if I type . … that’s when help-injection would be useful 😉

@csandfeld raises a very good point. Very rarely, if ever, do I ever want the block comment to be automatically closed.

@rkeithhill if we kept in the autoClosingPair for <##> can we still use <# or rather <##> as a help trigger? (assuming the proper setting is set to Block)

Good find @rkeithhill.

So the issue logged here comes from fixing issue https://github.com/Microsoft/vscode/issues/9799 in commit https://github.com/Microsoft/vscode/commit/2504d71ba327a3da44278286b2ccda148e354fb8.

Personally I see limited benefit of auto-closing block comments. Typically I use block comments to comment out parts of the code I am working on, during development. When doing that, auto-closing the block comment is just annoying, as I will have to remove the auto inserted #>, to place it where I want it.

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.

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?

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

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.