Parameter Help auto generation in PowerShell Functions

[fasteiner]

Prerequisites

• [X] I have written a descriptive issue title.
• [X] I have searched all issues to ensure it has not already been reported.

Summary

If you go above the parameter block of a function and write "##" the parameter help template is pre-generated automatically by the PowerShell Extension. However currently this generates:

<#
    .SYNOPSIS
    Short description
    
    .DESCRIPTION
    Long description
    
    .PARAMETER exampleParam
    Parameter description
    
    .EXAMPLE
    An example
    
    .NOTES
    General notes
    #>

However, it is best practice to also specify the return value of your function by using ".OUTPUTS", therefore it would be nice if this could be added to the default template / if the default template could be configured in the settings.json.

Proposed Design

This could be accomplished by either:

Static Design

Add ".OUTPUTS" to the current template

Dynamic Design

Add the possibility to specify the fields in the template in a list like:

 "powershell.extentention" : {
      "parameterHelp" : {
           "generatorTemplateFields" : [
               ".SYNOPSIS", ".DESCRIPTION", ".PARAMETER", ".EXAMPLE", ".NOTES", ".OUTPUTS"
            ]
      }
 }

[andyleejordan]

Thanks for writing this down for us!

[andyleejordan]

Oh gosh, ok so I found it and the news is mixed. No wonder this was hard to find, it's actually handled by PSScriptAnalyzer. Essentially ## triggers the GetCommentHelpHandler in PSES, and that calls into our analysis engine and fires out to PSSA's ProvideCommentHelp.

Might I suggest just for now to use the much better snippet we provide comment-help.

[SydneyhSmith]

@fasteiner is there a reason why we shouldn't add the complete template rather than just output? thanks for your help!

[fasteiner]

@SydneyhSmith I meant that the current template should be extended to also include ".OUTPUT". So it is also possible to always add the whole template (because this should also contain .OUTPUT)