Add missing types to `about_Type_Accelerators` and other changes

[surfingoldelephant]

Prerequisites

• Existing Issue: Search the existing issues for this repository. If there is an issue that fits your needs do not file a new one. Subscribe, react, or comment on that issue instead.
• Descriptive Title: Write the title for this issue as a short synopsis. If possible, provide context. For example, "Typo in Get-Foo cmdlet" instead of "Typo."
• Verify Version: If there is a mismatch between documentation and the behavior on your system, ensure that the version you are using is the same as the documentation. Check this box if they match or the issue you are reporting is not version specific.

Links

https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_type_accelerators

Summary

about_type_accelerators has various typos/minor errors and is missing two types from the list of available accelerators.

Also, see below for potential additions to the document.

Suggested Fix (Existing Content)

"SHORT DESCRIPTION"

• Change the heading to "Short description".
• Remove the reference to ".NET framework classes" in the description. Type accelerators pertain to any type category, not just classes. E.g., "Describes the accelerators available for .NET types".
• Update About topics accordingly.

"Long description"

• Similar to above regarding type categories.
• Emphasize that type accelerators are a convenience feature, but also have special functionality in some cases (see Special-cased type accelerators).
• Type accelerators are typically distinguished by being lowercase (aside from attribute type accelerators).
• Long description note:
  • A space is needed after "square brackets".
  • Note that this only applies to type literals (RuntimeType instances). Some contexts allow type accelerators specified as a string (e.g., '1' -as 'int', [type] 'int'). Other contexts like reflection require the type specified by its full name as a string.

"Available Type Accelerators"

• Change the heading to "Available type accelerators", "Built-in type accelerators" or "Default type accelerators".
• Add the following missing types to the 7.4, 7.5 and 7.6 lists:
  • NoRunspaceAffinity (System.Management.Automation.Language.NoRunspaceAffinityAttribute)
  • ValidateNotNullOrWhiteSpace (System.Management.Automation.ValidateNotNullOrWhiteSpaceAttribute)

Suggested Fix (Potential Additions)

Special-cased type accelerators

It would be useful to mention that some type accelerators are special-cased and behave differently to the type they alias. Notably, the following accelerators are special-cased:

• [pscustomobject]:
  • [pscustomobject] is aliased to Management.Automation.PSObject, not Management.Automation.PSCustomObject. Specifying it as, e.g., List<T>'s type does not restrict the list to custom objects. Similarly, the type accelerator cannot be used to meaningfully test for a custom object. See this issue.
  • [pscustomobject] serves a meaningful purpose with the following constructs:
    • [pscustomobject] @{...}: Constructs a new custom object, preserving property order.
    • [pscustomobject] $obj: Constructs a new custom object from the dictionary without preserving order, unless $obj is a dictionary type that respects order (e.g., Collections.Specialized.OrderedDictionary).
    • The aliased type (Management.Automation.PSObject) cannot be used with the same constructs.
• [ref]:
  • [ref] is special-cased in the compiler, but not the type it aliases.
  • Difference between [ref] and [System.Management.Automation.PSReference]

Programmatically get/add type accelerators

Using reflection, programmatically getting and adding type accelerators is possible.

• This is particularly useful in interactive, shell sessions for type exploration and extending the list of default accelerators.

• However, given the methods are not public, this requires a disclaimer regarding their future availability and limiting use to non-critical code (e.g., personal $PROFILE use only).

• Get (example):

  [psobject].Assembly.GetType('System.Management.Automation.TypeAccelerators')::Get |
      ForEach-Object -MemberName GetEnumerator |
      Sort-Object -CaseSensitive |
      Select-Object -Property @{ N = 'Accelerator'; E = 'Key' }, @{ N = 'Type'; E = 'Value' }
  
  # Accelerator                  Type
  # -----------                  ----
  # adsi                         System.DirectoryServices.DirectoryEntry
  # adsisearcher                 System.DirectoryServices.DirectorySearcher
  # Alias                        System.Management.Automation.AliasAttribute
  # [...]

• Add (example):

  [psobject].Assembly.GetType('System.Management.Automation.TypeAccelerators')::Add(
      'list', 
      [Collections.Generic.List[object]]
  )
  
  $list = [list] (1, 2, 3)
  $list.Count          # 3
  $list.GetType().Name # List`1