PowerShell - automate comment header - powershell

Question

When writing up a PowerShell script, what options are there to support template insertion that infers your parameters?
e.g. for the below, it'd somehow read you have $Name as a parameter, and then automatically produce something like below?
.SYNOPSIS
.DESCRIPTION
.PARAMETER Name
.PARAMETER Extension
function Add-Extension
{
param ([string]$Name,[string]$Extension = "txt")
$name = $name + "." + $extension
$name
<#
.SYNOPSIS
Adds a file name extension to a supplied name.
.DESCRIPTION
Adds a file name extension to a supplied name.
Takes any strings for the file name or extension.
.PARAMETER Name
Specifies the file name.
.PARAMETER Extension
Specifies the extension. "Txt" is the default.
.INPUTS
None. You cannot pipe objects to Add-Extension.
.OUTPUTS
System.String. Add-Extension returns a string with the extension or file name.
.EXAMPLE
C:\PS> extension -name "File"
File.txt
.EXAMPLE
C:\PS> extension -name "File" -extension "doc"
File.doc
.EXAMPLE
C:\PS> extension "File" "doc"
File.doc
.LINK
Online version: http://www.fabrikam.com/extension.html
.LINK
Set-Item
#>
}

Answer 1

What you're looking for is a feature of a PowerShell-aware editor or IDE.
The actively developed editor that offers the best PowerShell development experience, across platforms, is Visual Studio Code, combined with its PowerShell extension.
Once you have authored a function's implementation, you can place the cursor at either the start or the end of the function body and type ##, which scaffolds comment-based help for the function based on its parameters.
See also: Get-Help about_Comment_Based_Help, which explains the syntax of comment-based help.

Answer 2

If you want to discover the parameters of a defined function, you can do something like this:
# define function
function Add-Extension {
param([string]$Name, [string]$Extension)
}
# get command info for defined function
$cmdInfo = Get-Command Add-Extension
# compile command metadata from command info
$cmdMetadata = [System.Management.Automation.CommandMetadata]::new($cmdInfo)
Now you can access the individual parameters' metadata via $cmdMetadata.Parameters and generate your comment-based help content:
foreach($param in $cmdMetadata.Parameters.GetEnumerator()) {
".PARAMETER {0}" -f $param.Key
"[Insert parameter description for {0}]" -f $param.Key
""
}
There's one thing you might be interesting in that the parameter metadata won't contain though - the default value expression - for that, you'll need to parse the raw source code instead:
# parse script file containing the function
$scriptPath = Resolve-Path .\scriptWithFunctionDefinition.ps1
$AST = [System.Management.Automation.Language.Parser]::ParseFile($scriptPath, [ref]$null, [ref]$null)
# discover all the function definitions at the root level
$functionDefs = $AST.FindAll({ $args[0] -is [System.Management.Automation.Language.FunctionDefinitionAst] }, $false)
The Parser.ParseFile() method will return an abstract syntax tree - or AST for short - the elements of which we can inspect.
The FindAll() method will walk the AST and output any subtree that satisfies the condition - in this case we're looking for any [FunctionDefinitionAst], which, as the name implies, describes a function definition.
Now we can iterate the parameters like before:
foreach($functionDefinition in $functionDefs) {
# Since we're effectively dealing with code still,
# we need to handle both `function f(){}` and `function f{param()}` syntaxes
$parameters = $functionDefinition.Parameters
if($functionDefinition.Body.ParamBlock){
$parameters = $functionDefinition.Body.ParamBlock
}
# Now we can go through the actual parameters
foreach($parameter in $parameters){
".PARAMETER {0}" -f $parameter.Name.VariablePath
# ... and extract the default value expression
if($parameter.DefaultValue){
"Default value is {0}" -f $parameter.DefaultValue
}
}
}