Add an extended Snippet for Advanced Functions (#5203)

fixes #5197

Adds the ISE Advanced Function snippet, with some modern updates and adds placeholder support.

---------

Co-authored-by: Justin Grote <[email protected]>

Author: kilasuit

snippets/PowerShell.json

@@ -239,6 +239,101 @@
       "}"
     ]
   },
+  "Function-Advanced-Doc-Full-Example-From-ISE": {
+    "prefix": ["function-advanced-doc-fromISE", "cmdlet-doc-fromISE"],
+    "description": "Script advanced function definition with full comment-based help and parameter attributes.",
+    "body": [
+      "function ${1:Verb-Noun} {",
+      "\t<#",
+      "\t.SYNOPSIS",
+      "\t${2:Short description}",
+      "\t.DESCRIPTION",
+      "\t${3:Long description}",
+      "\t.EXAMPLE",
+      "\t${4:Example of how to use this cmdlet}",
+      "\t.EXAMPLE",
+      "\t${5:Another example of how to use this cmdlet}",
+      "\t.INPUTS",
+      "\t${6:Inputs to this cmdlet (if any)}",
+      "\t.OUTPUTS",
+      "\t${7:Output from this cmdlet (if any)}",
+      "\t.NOTES",
+      "\t${8:General notes}",
+      "\t.COMPONENT",
+      "\t${9:The component this cmdlet belongs to}",
+      "\t.ROLE",
+      "\t${10:The role this cmdlet belongs to}",
+      "\t.FUNCTIONALITY",
+      "\t${11:The functionality that best describes this cmdlet}",
+      "\t#>",
+      "\t[CmdletBinding(DefaultParameterSetName = '${12:ParameterSet1}',",
+      "\t\tSupportsShouldProcess,",
+      "\t\tPositionalBinding,",
+      "\t\tHelpUri = '${13:http://yourwebsiteforhelp.here}',",
+      "\t\tConfirmImpact = 'Medium')]",
+      "\t[Alias('${14:Be-lazyWithThis}','${15:lzy}','${16:Use-OldFunctionName}')]",
+      "\t[OutputType([${17:String}])]",
+      "\tparam (",
+      "\t\t# ${18:Param1} help description",
+      "\t\t[Parameter(Mandatory,",
+      "\t\t\tValueFromPipeline,",
+      "\t\t\tValueFromPipelineByPropertyName,",
+      "\t\t\tValueFromRemainingArguments,",
+      "\t\t\tPosition = 0,",
+      "\t\t\tParameterSetName = '${12:ParameterSet1}')]",
+      "\t\t[ValidateNotNull()]",
+      "\t\t[ValidateNotNullOrEmpty()]",
+      "\t\t[ValidateCount(0, 5)]",
+      "\t\t[ValidateSet(\"${19:sun}\", \"${20:moon}\", \"${21:earth}\")]",
+      "\t\t[Alias(\"${22:p1}\")]",
+      "\t\t$${18:Param1},",
+      "",
+      "\t\t# ${24:Param2} help description",
+      "\t\t[Parameter(ParameterSetName = '${12:ParameterSet1}')]",
+      "\t\t[AllowNull()]",
+      "\t\t[AllowEmptyCollection()]",
+      "\t\t[AllowEmptyString()]",
+      "\t\t[ValidateScript({ ${25:true} })]",
+      "\t\t[ValidateRange(0, 5)]",
+      "\t\t[${26:int}]",
+      "\t\t$${24:Param2},",
+      "",
+      "\t\t# ${28:Param3} help description",
+      "\t\t[Parameter(ParameterSetName = '${29:Another Parameter Set}')]",
+      "\t\t[ValidatePattern(\"${30:[a-z]*}\")]",
+      "\t\t[ValidateLength(0, 15)]",
+      "\t\t[${31:String}]",
+      "\t\t$${28:Param3},",
+      "",
+      "\t\t# ${33:Param4} help description",
+      "\t\t# Checkout the docs https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_functions_argument_completion?view=powershell-7.5#argumentcompletions-attribute on different ways to provide Argument Completion",
+      "\t\t[Parameter(ParameterSetName = '${34:Yet Another Parameter Set}')]",
+      "\t\t[ArgumentCompleter({'${35:add completer script}'})]",
+      "\t\t[ValidateLength(0, 15)]",
+      "\t\t[${36:String}]",
+      "\t\t$${33:Param4}",
+      "\t)",
+      "",
+      "\tbegin {",
+      "\t\t${38:#BeginCodeHere}",
+      "\t}",
+      "",
+      "\tprocess {",
+      "\t\tif (\\$pscmdlet.ShouldProcess(\"${39:Target}\", \"${40:Operation}\")) {",
+      "\t\t\t${41:#ProcessCodeHere}",
+      "\t\t}",
+      "\t}",
+      "",
+      "\tend {",
+      "\t\t${42:#EndCodeHere}",
+      "\t}",
+      "",
+      "\tclean {",
+      "\t\t${43:#CleanCodeHere} - Added in 7.3 for more information see https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_functions_advanced_methods?view=powershell-7.5#clean",
+      "\t}",
+      "}"
+    ]
+  },
   "Function-Inline": {
     "prefix": "function-inline",
     "description": "Function definition snippet that does not contain a param block, but defines parameters inline. This syntax is commonly used in other languages. More: Get-Help about_Functions",