Add information about numeric parameter names (#11623)

Author: sdwheeler

reference/5.1/Microsoft.PowerShell.Core/About/about_Functions_Advanced.md

@@ -1,7 +1,7 @@
 ---
 description: Introduces advanced functions that are a way to create cmdlets using scripts.
 Locale: en-US
-ms.date: 01/20/2023
+ms.date: 01/02/2025
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_functions_advanced?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about_Functions_Advanced
@@ -14,8 +14,8 @@ Introduces advanced functions that are a way to create cmdlets using scripts.
 ## Long description
 
 A cmdlet is a single command that participates in the pipeline semantics of
-PowerShell. This includes binary cmdlets, advanced script functions, CDXML, and
-Workflows.
+PowerShell. This includes binary cmdlets, PowerShell advanced script
+functions, CDXML, and Workflows.
 
 Advanced functions allow you create cmdlets that are written as a PowerShell
 function. Advanced functions make it easier to create cmdlets without having to
@@ -28,6 +28,12 @@ the Cmdlet attribute that's used in compiled cmdlet classes to identify the
 class as a cmdlet. For more information about this attribute, see
 [about_Functions_CmdletBindingAttribute][03].
 
+The parameters of the function are variables declared in the `param()`
+statement. You can use the optional `[Parameter()]` attribute alone or in
+combination with the `[Alias()]` attribute or any of the parameter validation
+attributes. For more information about how to declare parameters, see
+[about_Functions_Advanced_Parameters][02].
+
 The following example shows a function that accepts a name and then prints a
 greeting using the supplied name. Also notice that this function defines a name
 that includes a verb (Send) and noun (Greeting) pair like the verb-noun pair of
@@ -37,36 +43,29 @@ a compiled cmdlet. However, functions aren't required to have a verb-noun name.
 function Send-Greeting
 {
     [CmdletBinding()]
-    Param(
+    param(
         [Parameter(Mandatory=$true)]
         [string] $Name
     )
 
-    Process
+    process
     {
         Write-Host ("Hello " + $Name + "!")
     }
 }
 ```
 
-The parameters of the function are declared using the `Parameter` attribute.
-This attribute can be used alone, or it can be combined with the Alias
-attribute or with several other parameter validation attributes. For more
-information about how to declare parameters (including dynamic parameters that
-are added at runtime), see [about_Functions_Advanced_Parameters][02].
-
-The actual work of the previous function is performed in the `process` block,
-which is equivalent to the **ProcessingRecord** method that's used by compiled
-cmdlets to process the data that's passed to the cmdlet. This block, along with
-the `begin` and `end` blocks, is described in the
-[about_Functions_Advanced_Methods][01] topic.
+This function performs the work in the `process` block, which is equivalent to
+the **ProcessingRecord** method used in compiled cmdlets. The `process` block
+and the other named blocks are described in
+[about_Functions_Advanced_Methods][01].
 
 Advanced functions differ from compiled cmdlets in the following ways:
 
 - Advanced function parameter binding doesn't throw an exception when an array
   of strings is bound to a **Boolean** parameter.
-- The `ValidateSet` attribute and the `ValidatePattern` attribute can't pass named
-  parameters.
+- The `ValidateSet` attribute and the `ValidatePattern` attribute can't pass
+  named parameters.
 - Advanced functions can't be used in transactions.
 
 ## See also
@@ -76,10 +75,12 @@ Advanced functions differ from compiled cmdlets in the following ways:
 - [about_Functions_Advanced_Parameters][02]
 - [about_Functions_CmdletBindingAttribute][03]
 - [about_Functions_OutputTypeAttribute][04]
+- [about_Variables][06]
 
 <!-- link references -->
 [01]: about_Functions_Advanced_Methods.md
 [02]: about_Functions_Advanced_Parameters.md
 [03]: about_Functions_CmdletBindingAttribute.md
 [04]: about_Functions_OutputTypeAttribute.md
 [05]: about_Functions.md
+[06]: about_Variables.md

reference/5.1/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md

@@ -1,7 +1,7 @@
 ---
 description: Explains how to add parameters to advanced functions.
 Locale: en-US
-ms.date: 07/02/2024
+ms.date: 01/02/2025
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_functions_advanced_parameters?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about_Functions_Advanced_Parameters
@@ -28,6 +28,60 @@ the parameters in a command. Splatting is valid on simple and advanced
 functions. For more information, see [about_Functions][14] and
 [about_Splatting][17].
 
+## Parameter declaration
+
+Parameters are variables declared in the `param()` statement of a function or
+script block. You can use the optional `[Parameter()]` attribute alone or in
+combination with the `[Alias()]` attribute or any of the parameter validation
+attributes.
+
+Parameter names follow the rules for variable names. Parameter names consist of
+decimal digits, alphabetic characters, and underscores. For a complete list of
+naming rules, see [about_Variables][20].
+
+> [!IMPORTANT]
+> It's possible to name a parameter using only decimal digits. Using numeric
+> parameter names isn't recommended because it can lead to confusion with
+> positional parameters.
+
+Consider the following example:
+
+```powershell
+function TestFunction {
+    param (
+        [switch] $100,
+        [string] $200
+    )
+
+    "100: $100"
+    "200: $200"
+}
+```
+
+If you try to use the parameters, PowerShell interprets them as negative
+numbers passed as positional parameter.
+
+```powershell
+PS> TestFunction -100 -200 Hello
+100: False
+200: -100
+$args: -200 Hello
+```
+
+The output shows that PowerShell has bound the value `-100` to the `$200`
+parameter variable. The remaining positional values are bound to `$args`. To
+work around the issue, you can use splatting to pass the parameter values.
+
+```powershell
+PS> $ht = @{100 = $true; 200 = 'Hello'}
+PS> TestFunction @ht
+100: True
+200: Hello
+$args:
+```
+
+For more information, see [about_Splatting][17].
+
 ## Type conversion of parameter values
 
 When you supply strings as arguments to parameters that expect a different
@@ -104,6 +158,8 @@ At line:13 char:15
     + FullyQualifiedErrorId : ParameterArgumentTransformationError,Get-Date_Func
 ```
 
+For more information, see [about_Type_Conversion](about_Type_Conversion.md).
+
 ## Static parameters
 
 Static parameters are parameters that are always available in the function.
@@ -1177,7 +1233,7 @@ True
 - [about_Functions_OutputTypeAttribute][13]
 
 <!-- link references -->
-[01]: ./about_comment_based_help.md
+[01]: about_comment_based_help.md
 [02]: /dotnet/api/system.management.automation.runtimedefinedparameter
 [05]: about_Automatic_Variables.md
 [06]: about_CommonParameters.md
@@ -1192,3 +1248,4 @@ True
 [17]: about_Splatting.md
 [18]: about_Tab_Expansion.md
 [19]: about_Wildcards.md
+[20]: about_Variables.md

reference/5.1/Microsoft.PowerShell.Core/About/about_Variables.md

@@ -1,7 +1,7 @@
 ---
 description: Describes how variables store values that can be used in PowerShell.
 Locale: en-US
-ms.date: 03/07/2024
+ms.date: 01/02/2025
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_variables?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about_Variables
@@ -321,15 +321,16 @@ Alphanumeric variable names can contain these characters:
 - Underscore (`_`) character.
 - Question mark (`?`) character.
 
-The following list contains the Unicode category descriptions. For more
-information, see [UnicodeCategory][17].
+The following list contains the .NET names of the Unicode categories with a
+description. For more information, see [UnicodeCategory][17].
 
-- **Lu** - UppercaseLetter
-- **Ll** - LowercaseLetter
-- **Lt** - TitlecaseLetter
-- **Lm** - ModifierLetter
-- **Lo** - OtherLetter
-- **Nd** - DecimalDigitNumber
+- **Lu** - UppercaseLetter - an uppercase letter
+- **Ll** - LowercaseLetter - a lowercase letter
+- **Lt** - TitlecaseLetter - a digraph encoded as a single character with the
+  first part uppercase
+- **Lm** - ModifierLetter - a modifier letter
+- **Lo** - OtherLetter - other letters, including syllables and ideographs
+- **Nd** - DecimalDigitNumber - a decimal digit
 
 To create or display a variable name that includes spaces or special
 characters, enclose the variable name with the curly braces (`{}`) characters.

reference/7.4/Microsoft.PowerShell.Core/About/about_Functions_Advanced.md

@@ -1,7 +1,7 @@
 ---
 description: Introduces advanced functions that are a way to create cmdlets using scripts.
 Locale: en-US
-ms.date: 01/20/2023
+ms.date: 01/02/2025
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_functions_advanced?view=powershell-7.4&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about_Functions_Advanced
@@ -14,8 +14,8 @@ Introduces advanced functions that are a way to create cmdlets using scripts.
 ## Long description
 
 A cmdlet is a single command that participates in the pipeline semantics of
-PowerShell. This includes binary cmdlets, advanced script functions, CDXML, and
-Workflows.
+PowerShell. This includes binary cmdlets, PowerShell advanced functions, and
+CDXML cmdlets.
 
 Advanced functions allow you create cmdlets that are written as a PowerShell
 function. Advanced functions make it easier to create cmdlets without having to
@@ -28,6 +28,12 @@ the Cmdlet attribute that's used in compiled cmdlet classes to identify the
 class as a cmdlet. For more information about this attribute, see
 [about_Functions_CmdletBindingAttribute][03].
 
+The parameters of the function are variables declared in the `param()`
+statement. You can use the optional `[Parameter()]` attribute alone or in
+combination with the `[Alias()]` attribute or any of the parameter validation
+attributes. For more information about how to declare parameters, see
+[about_Functions_Advanced_Parameters][02].
+
 The following example shows a function that accepts a name and then prints a
 greeting using the supplied name. Also notice that this function defines a name
 that includes a verb (Send) and noun (Greeting) pair like the verb-noun pair of
@@ -37,36 +43,29 @@ a compiled cmdlet. However, functions aren't required to have a verb-noun name.
 function Send-Greeting
 {
     [CmdletBinding()]
-    Param(
+    param(
         [Parameter(Mandatory=$true)]
         [string] $Name
     )
 
-    Process
+    process
     {
         Write-Host ("Hello " + $Name + "!")
     }
 }
 ```
 
-The parameters of the function are declared using the `Parameter` attribute.
-This attribute can be used alone, or it can be combined with the Alias
-attribute or with several other parameter validation attributes. For more
-information about how to declare parameters (including dynamic parameters that
-are added at runtime), see [about_Functions_Advanced_Parameters][02].
-
-The actual work of the previous function is performed in the `process` block,
-which is equivalent to the **ProcessingRecord** method that's used by compiled
-cmdlets to process the data that's passed to the cmdlet. This block, along with
-the `begin` and `end` blocks, is described in the
-[about_Functions_Advanced_Methods][01] topic.
+This function performs the work in the `process` block, which is equivalent to
+the **ProcessingRecord** method used in compiled cmdlets. The `process` block
+and the other named blocks are described in
+[about_Functions_Advanced_Methods][01].
 
 Advanced functions differ from compiled cmdlets in the following ways:
 
 - Advanced function parameter binding doesn't throw an exception when an array
   of strings is bound to a **Boolean** parameter.
-- The `ValidateSet` attribute and the `ValidatePattern` attribute can't pass named
-  parameters.
+- The `ValidateSet` attribute and the `ValidatePattern` attribute can't pass
+  named parameters.
 - Advanced functions can't be used in transactions.
 
 ## See also
@@ -76,10 +75,12 @@ Advanced functions differ from compiled cmdlets in the following ways:
 - [about_Functions_Advanced_Parameters][02]
 - [about_Functions_CmdletBindingAttribute][03]
 - [about_Functions_OutputTypeAttribute][04]
+- [about_Variables][06]
 
 <!-- link references -->
 [01]: about_Functions_Advanced_Methods.md
 [02]: about_Functions_Advanced_Parameters.md
 [03]: about_Functions_CmdletBindingAttribute.md
 [04]: about_Functions_OutputTypeAttribute.md
 [05]: about_Functions.md
+[06]: about_Variables.md