Fixes #12605 - Update description of instantiation syntax

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

@@ -1,7 +1,7 @@
 ---
 description: Describes how you can use classes to create your own custom types.
 Locale: en-US
-ms.date: 01/19/2024
+ms.date: 01/22/2026
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_classes?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about_Classes
@@ -64,18 +64,17 @@ To instantiate an instance of a class, use one of the following syntaxes:
 ```
 
 ```Syntax
-[$<variable-name> =] [<class-name>]@{[<class-property-hashtable>]}
+[$<variable-name> =] [<class-name>]<convertable-value-type>
 ```
 
 > [!NOTE]
 > When using the `[<class-name>]::new()` syntax, brackets around the class name
 > are mandatory. The brackets signal a type definition for PowerShell.
 >
-> The hashtable syntax only works for classes that have a default constructor
-> that doesn't expect any parameters. It creates an instance of the class with
-> the default constructor and then assigns the key-value pairs to the instance
-> properties. If any key in the hashtable isn't a valid property name,
-> PowerShell raises an error.
+> The `<convertable-value-type>` syntax only works for classes that have a
+> default constructor that doesn't expect any parameters. It creates an
+> instance of the class with the default constructor and then uses runtime type
+> conversion to assign the values provided.
 
 ## Examples
 
@@ -99,7 +98,67 @@ Brand
 Fabrikam, Inc.
 ```
 
-### Example 2 - Class with instance members
+### Example 2 - Using instantiation syntax
+
+This example defines a **Book** class with several properties, but no
+constructor.
+
+```powershell
+class Book {
+    # Class properties
+    [string]   $Title
+    [string]   $Author
+    [string]   $Synopsis
+    [string]   $Publisher
+    [datetime] $PublishDate
+    [int]      $PageCount
+    [string[]] $Tags
+}
+```
+
+The following example shows how the default constructor can assign the values
+from a compatible value using type coercion. In this example, a hashtable is
+used to provide the property values.
+
+```powershell
+$Book1 = [Book] @{
+    Title       = '1984'
+    Author      = 'George Orwell'
+    Synopsis    = ''
+    Publisher   = 'Secker & Warburg'
+    PublishDate = '1949-06-08'
+    PageCount   = 328
+    Tags        = @('Dystopian', 'Political Fiction', 'Social Science Fiction')
+}
+$Book1
+```
+
+```Output
+Title       : 1984
+Author      : George Orwell
+Synopsis    :
+Publisher   : Secker & Warburg
+PublishDate : 6/8/1949 12:00:00 AM
+PageCount   : 328
+Tags        : {Dystopian, Political Fiction, Social Science Fiction}
+```
+
+The key-value pairs of the hashtable are assigned to the instance properties.
+If any key in the hashtable isn't a valid property name, instantiation fails.
+
+In this example, an array is used to provide the values for the generic list.
+
+```powershell
+$List =  [System.Collections.Generic.List[int]] @(42, 43)
+$List
+```
+
+```Output
+42
+43
+```
+
+### Example 3 - Class with instance members
 
 This example defines a **Book** class with several properties, constructors,
 and methods. Every defined member is an _instance_ member, not a static member.
@@ -190,12 +249,12 @@ It takes 10 hours and 20 minutes to read The Hobbit by J.R.R. Tolkien (1937),
 which was published 86 years ago.
 ```
 
-### Example 3 - Class with static members
+### Example 4 - Class with static members
 
-The **BookList** class in this example builds on the **Book** class in example
-2. While the **BookList** class can't be marked static itself, the
-implementation only defines the **Books** static property and a set of static
-methods for managing that property.
+The **BookList** class in this example builds on the **Book** class in the
+previous example. While the **BookList** class can't be marked static itself,
+the implementation only defines the **Books** static property and a set of
+static methods for managing that property.
 
 ```powershell
 class BookList {
@@ -369,7 +428,7 @@ Properties are variables declared in the class scope. A property can be of any
 built-in type or an instance of another class. Classes can have zero or more
 properties. Classes don't have a maximum property count.
 
-For more information, see [about_Classes_Properties][01].
+For more information, see [about_Classes_Properties][10].
 
 ## Class methods
 
@@ -379,7 +438,7 @@ method doesn't return any output, it must have the **Void** output type. If a
 method doesn't explicitly define an output type, the method's output type is
 **Void**.
 
-For more information, see [about_Classes_Methods][02].
+For more information, see [about_Classes_Methods][05].
 
 ## Class constructors
 
@@ -388,7 +447,7 @@ moment of creating the instance of the class. Constructors have the same name
 as the class. Constructors might have parameters, to initialize the data
 members of the new object.
 
-For more information, see [about_Classes_Constructors][03].
+For more information, see [about_Classes_Constructors][01].
 
 ## Hidden keyword
 
@@ -417,11 +476,11 @@ Hidden class members are:
 > When you hide any constructor, the `new()` option is removed from
 > IntelliSense and completion results.
 
-For more information about the keyword, see [about_Hidden][04]. For more
-information about hidden properties, see [about_Classes_Properties][05]. For
+For more information about the keyword, see [about_Hidden][12]. For more
+information about hidden properties, see [about_Classes_Properties][09]. For
 more information about hidden methods, see [about_Classes_Methods][06]. For
 more information about hidden constructors, see
-[about_Classes_Constructors][07].
+[about_Classes_Constructors][02].
 
 ## Static keyword
 
@@ -435,9 +494,9 @@ available always. All static properties live for the entire session span.
 The `static` keyword only applies to class members, not a class itself.
 
 For more information about static properties, see
-[about_Classes_Properties][08]. For more information about static methods, see
-[about_Classes_Methods][09]. For more information about static constructors,
-see [about_Classes_Constructors][10].
+[about_Classes_Properties][10]. For more information about static methods, see
+[about_Classes_Methods][07]. For more information about static constructors,
+see [about_Classes_Constructors][03].
 
 ## Inheritance in PowerShell classes
 
@@ -453,8 +512,7 @@ inherits from an interface must implement that contract. When it does, the
 class can be used like any other class implementing that interface.
 
 For more information about deriving classes that inherit from a base class or
-implement interfaces, see
-[about_Classes_Inheritance][11].
+implement interfaces, see [about_Classes_Inheritance][04].
 
 ## Export classes with type accelerators
 
@@ -540,7 +598,7 @@ consistently import classes defined in nested modules or classes defined in
 scripts that are dot-sourced into the root module. Define classes that you want
 to be available to users outside of the module directly in the root module.
 
-For more information about the `using` statement, see [about_Using][12].
+For more information about the `using` statement, see [about_Using][15].
 
 ## Load newly changed code during development
 
@@ -567,7 +625,7 @@ parameters can't be used with class members. The **PSReference** class was
 designed to support COM objects. COM objects have cases where you need to pass
 a value in by reference.
 
-For more information, see [PSReference Class][13].
+For more information, see [PSReference Class][16].
 
 ## Limitations
 
@@ -681,30 +739,30 @@ workaround for those limitations, if any.
 
 ## See also
 
-- [about_Classes_Constructors][03]
-- [about_Classes_Inheritance][11]
-- [about_Classes_Methods][02]
-- [about_Classes_Properties][01]
-- [about_Enum][14]
-- [about_Hidden][04]
-- [about_Language_Keywords][15]
-- [about_Methods][16]
-- [about_Using][12]
+- [about_Classes_Constructors][01]
+- [about_Classes_Inheritance][04]
+- [about_Classes_Methods][05]
+- [about_Classes_Properties][08]
+- [about_Enum][11]
+- [about_Hidden][12]
+- [about_Language_Keywords][13]
+- [about_Methods][14]
+- [about_Using][15]
 
 <!-- link references -->
-[01]: about_Classes_Properties.md
-[02]: about_Classes_Methods.md
-[03]: about_Classes_Constructors.md
-[04]: about_Hidden.md
-[05]: about_Classes_Properties.md#hidden-properties
+[01]: about_Classes_Constructors.md
+[02]: about_Classes_Constructors.md#hidden-constructors
+[03]: about_Classes_Constructors.md#static-constructors
+[04]: about_Classes_Inheritance.md
+[05]: about_Classes_Methods.md
 [06]: about_Classes_Methods.md#hidden-methods
-[07]: about_Classes_Constructors.md#hidden-constructors
-[08]: about_Classes_Properties.md#static-properties
-[09]: about_Classes_Methods.md#static-methods
-[10]: about_Classes_Constructors.md#static-constructors
-[11]: about_Classes_Inheritance.md
-[12]: about_Using.md
-[13]: /dotnet/api/system.management.automation.psreference
-[14]: about_Enum.md
-[15]: about_language_keywords.md
-[16]: about_methods.md
+[07]: about_Classes_Methods.md#static-methods
+[08]: about_Classes_Properties.md
+[09]: about_Classes_Properties.md#hidden-properties
+[10]: about_Classes_Properties.md#static-properties
+[11]: about_Enum.md
+[12]: about_Hidden.md
+[13]: about_language_keywords.md
+[14]: about_methods.md
+[15]: about_Using.md
+[16]: xref:System.Management.Automation.PSReference