Add info and link to about_Comments (#11749)

Author: sdwheeler

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

@@ -1,7 +1,7 @@
 ---
 description: Describes regular expressions in PowerShell.
 Locale: en-US
-ms.date: 06/14/2024
+ms.date: 01/30/2025
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_regular_expressions?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about_Regular_Expressions
@@ -17,19 +17,20 @@ Describes regular expressions in PowerShell.
 > [!NOTE]
 > This article shows the syntax and methods for using regular expressions in
 > PowerShell. It doesn't cover all possible expressions. For a more complete
-> reference, see the [Regular Expression Language - Quick Reference][03].
+> reference, see the [Regular Expression Language - Quick Reference][02].
 
 A regular expression is a pattern used to match text. It can be made up of
-literal characters, operators, and other constructs.
+literal characters, operators, and other constructs. PowerShell uses the
+[.NET regex][03] engine.
 
 This article demonstrates regular expression syntax in PowerShell. PowerShell
 has several operators and cmdlets that use regular expressions. You can read
 more about their syntax and usage at the links below.
 
-- [Select-String][10]
-- [-match and -replace operators][06]
-- [-split operator][08]
-- [switch statement with -regex option][09]
+- [Select-String][11]
+- [-match and -replace operators][07]
+- [-split operator][09]
+- [switch statement with -regex option][10]
 
 PowerShell regular expressions are case-insensitive by default. Each method
 shown above has a different way to force case sensitivity.
@@ -81,8 +82,8 @@ characters).
 
 ### Numbers
 
-The `\d` character class will match any decimal digit. Conversely, `\D` will
-match any character except decimal digits.
+The `\d` character class matchs any decimal digit. Conversely, `\D` matches any
+character except decimal digits.
 
 ```powershell
 # This expression returns true if it matches a server name.
@@ -92,7 +93,7 @@ match any character except decimal digits.
 
 ### Word characters
 
-The `\w` character class will match any word character `[a-zA-Z_0-9]`. To match
+The `\w` character class matches any word character `[a-zA-Z_0-9]`. To match
 any non-word character, use `\W`.
 
 ```powershell
@@ -103,8 +104,8 @@ any non-word character, use `\W`.
 
 ### Wildcards
 
-The period (`.`) is a wildcard character in regular expressions. It will match
-any character except a newline (`\n`).
+The period (`.`) is a wildcard character in regular expressions. It matches any
+character except a newline (`\n`).
 
 ```powershell
 # This expression returns true.
@@ -155,7 +156,7 @@ The plus sign (`+`) matches the previous element one or more times.
 ```
 
 The question mark `?` matches the previous element zero or one time. Like
-asterisk `*`, it will even match strings where the element is absent.
+asterisk `*`, it even matches strings where the element is absent.
 
 ```powershell
 # This returns true for any server name, even server names without dashes.
@@ -208,7 +209,7 @@ When using anchors in PowerShell, you should understand the difference between
   instead of matching every character EXCEPT the newline `\n`.
 
 To read more about these options and how to use them, visit the
-[Regular Expression Language - Quick Reference][03].
+[Regular Expression Language - Quick Reference][02].
 
 ## Escaping characters
 
@@ -354,7 +355,7 @@ The provided regular expression extracts the username and domain from the
 message and stores them under the keys:**N** for name and **D** for domain.
 
 ```powershell
-$log = (Get-EventLog -LogName Security -Newest 1 -InstanceId 4689).Message
+$log = (Get-WinEvent -LogName Security -MaxEvents 1).Message
 $r = '(?s).*Account Name:\s*(?<N>.*).*Account Domain:\s*(?<D>[A-Z,0-9]*)'
 $log -match $r
 ```
@@ -372,10 +373,10 @@ Name                           Value
 ----                           -----
 D                              CONTOSO
 N                              jsmith
-0                              A process has exited....
+0                              A process has exited...
 ```
 
-For more information, see [Grouping Constructs in Regular Expressions][02].
+For more information, see [Grouping Constructs in Regular Expressions][01].
 
 ### Substitutions in Regular Expressions
 
@@ -461,18 +462,32 @@ Gobble Gobble
 For detailed information on substitution expressions, see
 [Substitutions in Regular Expressions][04].
 
+## Comments in regular expressions
+
+Regular expressions can be very complex and difficult to read. You can use
+comments to make them more understandable. There are two types of comments
+allowed in regular expressions.
+
+- Inline comment (`(?#)`)
+- End-of-line comment (`#`)
+
+For more information, see the _Regular expression comments_ section of
+[about_Comments][05].
+
 ## See also
 
-- [about_Operators][07]
-- [about_Comparison_Operators][05]
+- [about_Operators][08]
+- [about_Comparison_Operators][06]
 
 <!-- link references -->
-[02]: /dotnet/standard/base-types/grouping-constructs-in-regular-expressions
-[03]: /dotnet/standard/base-types/regular-expression-language-quick-reference
+[01]: /dotnet/standard/base-types/grouping-constructs-in-regular-expressions
+[02]: /dotnet/standard/base-types/regular-expression-language-quick-reference
+[03]: /dotnet/standard/base-types/regular-expressions
 [04]: /dotnet/standard/base-types/substitutions-in-regular-expressions
-[05]: about_Comparison_Operators.md
-[06]: about_Comparison_Operators.md#matching-operators
-[07]: about_Operators.md
-[08]: about_Split.md
-[09]: about_Switch.md
-[10]: xref:Microsoft.PowerShell.Utility.Select-String
+[05]: about_Comments.md#regular-expression-comments
+[06]: about_Comparison_Operators.md
+[07]: about_Comparison_Operators.md#matching-operators
+[08]: about_Operators.md
+[09]: about_Split.md
+[10]: about_Switch.md
+[11]: xref:Microsoft.PowerShell.Utility.Select-String

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

@@ -1,7 +1,7 @@
 ---
 description: Explains how to sign scripts so that they comply with the PowerShell execution policies.
 Locale: en-US
-ms.date: 01/07/2025
+ms.date: 01/30/2025
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_signing?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about_Signing
@@ -15,7 +15,7 @@ policies.
 
 ## Long description
 
-The Restricted execution policy doesn't permit any scripts to run. The
+The **Restricted** execution policy doesn't permit any scripts to run. The
 **AllSigned** and **RemoteSigned** execution policies prevent PowerShell from
 running scripts that don't have a digital signature.
 
@@ -141,10 +141,8 @@ certificate. Two types of certificates are suitable for signing a script file:
   not run on other computers.
 
 Self-signed certificate should only be used to sign scripts for testing
-purposes.
-
-It isn't appropriate for scripts that will be shared, even within an
-enterprise.
+purposes. Self-signed certificates aren't appropriate for scripts that you want
+to share.
 
 If you create a self-signed certificate, be sure to enable strong private key
 protection on your certificate. This prevents malicious programs from signing
@@ -220,7 +218,7 @@ Directory: Microsoft.PowerShell.Security\Certificate::CurrentUser\My
 
 Thumbprint                                Subject
 ----------                                -------
-4D4917CB140714BA5B81B96E0B18AAF2C4564FDF  CN=PowerShell User ]
+4D4917CB140714BA5B81B96E0B18AAF2C4564FDF  CN=PowerShell User
 ```
 
 ## Sign a script
@@ -265,6 +263,10 @@ $cert = Get-ChildItem Cert:\CurrentUser\My -CodeSigningCert |
 Set-AuthenticodeSignature add-signature.ps1 $cert
 ```
 
+The `Set-AuthenticodeSignature` cmdlet adds the signature to the script file as
+a comment block at the end of the file. The comment block begins and ends with
+`# SIG #`.
+
 After you sign the script, you can run it on the local computer. However, the
 script won't run on computers where the PowerShell execution policy requires a
 digital signature from a trusted authority. If you try, PowerShell displays the

reference/5.1/Microsoft.PowerShell.Utility/ConvertFrom-Json.md

@@ -2,7 +2,7 @@
 external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml
 Locale: en-US
 Module Name: Microsoft.PowerShell.Utility
-ms.date: 11/29/2023
+ms.date: 01/30/2025
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/convertfrom-json?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: ConvertFrom-Json
@@ -35,10 +35,11 @@ To generate a JSON string from any object, use the `ConvertTo-Json` cmdlet.
 This cmdlet was introduced in PowerShell 3.0.
 
 > [!NOTE]
-> Beginning with PowerShell 6, the cmdlet supports JSON with comments. JSON comments start with two
-> forward slashes (`//`) characters. JSON comments aren't captured in the objects output by the
-> cmdlet. Prior to PowerShell 6, `ConvertFrom-Json` would return an error when it encountered a JSON
-> comment.
+> In Windows PowerShell 5.1, `ConvertFrom-Json` returns an error when it encounters a JSON
+> comment. In PowerShell 6 and higher, the cmdlet supports JSON with comments. JSON comments aren't
+> captured in the objects output by the cmdlet. For more information, see the _JSON comments_
+> section of the
+> [about_Comments](/powershell/module/microsoft.powershell.core/about/about_comments) article.
 
 ## EXAMPLES
 

reference/5.1/Microsoft.PowerShell.Utility/Invoke-RestMethod.md

@@ -32,7 +32,8 @@ The `Invoke-RestMethod` cmdlet sends HTTP and HTTPS requests to Representational
 
 PowerShell formats the response based to the data type. For an RSS or ATOM feed, PowerShell returns
 the Item or Entry XML nodes. For JavaScript Object Notation (JSON) or XML, PowerShell converts, or
-deserializes, the content into `[PSCustomObject]` objects.
+deserializes, the content into `[PSCustomObject]` objects. Comments aren't permitted in the JSON
+data.
 
 > [!NOTE]
 > When the REST endpoint returns multiple objects, the objects are received as an array. If you pipe
@@ -205,11 +206,11 @@ Accept wildcard characters: False
 
 ### -Certificate
 
-Specifies the client certificate that is used for a secure web request. Enter a variable that
+Specifies the client certificate that's used for a secure web request. Enter a variable that
 contains a certificate or a command or expression that gets the certificate.
 
 To find a certificate, use `Get-PfxCertificate` or use the `Get-ChildItem` cmdlet in the Certificate
-(`Cert:`) drive. If the certificate is not valid or does not have sufficient authority, the command
+(`Cert:`) drive. If the certificate isn't valid or doesn't have sufficient authority, the command
 fails.
 
 ```yaml
@@ -252,7 +253,7 @@ Accept wildcard characters: False
 Specifies the content type of the web request.
 
 If this parameter is omitted and the request method is POST, `Invoke-RestMethod` sets the content
-type to "application/x-www-form-urlencoded". Otherwise, the content type is not specified in the
+type to `application/x-www-form-urlencoded`. Otherwise, the content type isn't specified in the
 call.
 
 ```yaml
@@ -305,7 +306,7 @@ Aliases:
 
 Required: False
 Position: Named
-Default value: KeepAlive
+Default value: False
 Accept pipeline input: False
 Accept wildcard characters: False
 ```
@@ -453,14 +454,14 @@ Accept wildcard characters: False
 
 ### -ProxyCredential
 
-Specifies a user account that has permission to use the proxy server that is specified by the
+Specifies a user account that has permission to use the proxy server that's specified by the
 **Proxy** parameter. The default is the current user.
 
-Type a user name, such as "User01" or "Domain01\User01", or enter a **PSCredential** object, such as
-one generated by the `Get-Credential` cmdlet.
+Type a user name, such as "User01" or "Domain01\User01", or enter a **PSCredential** object, such
+as one generated by the `Get-Credential` cmdlet.
 
-This parameter is valid only when the **Proxy** parameter is also used in the command. You cannot
-use the **ProxyCredential** and **ProxyUseDefaultCredentials** parameters in the same command.
+This parameter is valid only when the **Proxy** parameter is also used in the command. You can't use
+the **ProxyCredential** and **ProxyUseDefaultCredentials** parameters in the same command.
 
 ```yaml
 Type: System.Management.Automation.PSCredential
@@ -479,8 +480,8 @@ Accept wildcard characters: False
 Uses the credentials of the current user to access the proxy server that is specified by the
 **Proxy** parameter.
 
-This parameter is valid only when the **Proxy** parameter is also used in the command. You cannot
-use the **ProxyCredential** and **ProxyUseDefaultCredentials** parameters in the same command.
+This parameter is valid only when the **Proxy** parameter is also used in the command. You can't use
+the **ProxyCredential** and **ProxyUseDefaultCredentials** parameters in the same command.
 
 ```yaml
 Type: System.Management.Automation.SwitchParameter
@@ -576,7 +577,7 @@ Accept wildcard characters: False
 
 ### -Uri
 
-Specifies the Uniform Resource Identifier (URI) of the Internet resource to which the web request is
+Specifies the Uniform Resource Identifier (URI) of the internet resource to which the web request is
 sent. This parameter supports HTTP, HTTPS, FTP, and FILE values.
 
 This parameter is required. The parameter name (**Uri**) is optional.
@@ -630,12 +631,13 @@ Accept wildcard characters: False
 
 Specifies a user agent string for the web request.
 
-The default user agent is similar to "Mozilla/5.0 (Windows NT; Windows NT 6.1; en-US)
-WindowsPowerShell/3.0" with slight variations for each operating system and platform.
+The default user agent is similar to
+`Mozilla/5.0 (Windows NT 10.0; Microsoft Windows 10.0.15063; en-US) PowerShell/6.0.0` with slight
+variations for each operating system and platform.
 
-To test a website with the standard user agent string that is used by most Internet browsers, use
-the properties of the [PSUserAgent](/dotnet/api/microsoft.powershell.commands) class, such as
-Chrome, Firefox, Internet Explorer, Opera, and Safari.
+To test a website with the standard user agent string that's used by most internet browsers, use
+the properties of the [PSUserAgent](xref:Microsoft.PowerShell.Commands.PSUserAgent) class, such as
+Chrome, Firefox, InternetExplorer, Opera, and Safari.
 
 ```yaml
 Type: System.String
@@ -656,17 +658,17 @@ Specifies a web request session. Enter the variable name, including the dollar s
 To override a value in the web request session, use a cmdlet parameter, such as **UserAgent** or
 **Credential**. Parameter values take precedence over values in the web request session.
 
-Unlike a remote session, the web request session is not a persistent connection. It is an object
-that contains information about the connection and the request, including cookies, credentials, the
+Unlike a remote session, the web request session isn't a persistent connection. It's an object that
+contains information about the connection and the request, including cookies, credentials, the
 maximum redirection value, and the user agent string. You can use it to share state and data among
 web requests.
 
-To create a web request session, enter a variable name (without a dollar sign) in the value of the
+To create a web request session, enter a variable name, without a dollar sign, in the value of the
 **SessionVariable** parameter of an `Invoke-RestMethod` command. `Invoke-RestMethod` creates the
 session and saves it in the variable. In subsequent commands, use the variable as the value of the
 **WebSession** parameter.
 
-You cannot use the **SessionVariable** and **WebSession** parameters in the same command.
+You can't use the **SessionVariable** and **WebSession** parameters in the same command.
 
 ```yaml
 Type: Microsoft.PowerShell.Commands.WebRequestSession