CODEWITHSUNDEEP
powershellmacroscomments
ThingsAreBroken
ThingsAreBroken

Reputation: 27

PowerShell - automate comment header

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
    #>
}

Upvotes: 1

Views: 2488

Answers (2)

Mathias R. Jessen
Mathias R. Jessen

Reputation: 174710

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
    }
  }
}

Upvotes: 2

mklement0
mklement0

Reputation: 439287

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.

Upvotes: 1

Related Questions