Start updating the documentation comments (QOL) (#4689)

* Start updating the documentation comments (QOL)

* No inheritdoc for ToString in KerberosSupplementalTicket.cs

* Update JObject.cs

* Update based on build suggestions

* Remarks cannot be used on an enum

* Update TokenCache.cs

* Create a PCA bootstrap sample in the docs

* Update JObject.cs

* Update src/client/Microsoft.Identity.Client/UiRequiredExceptionClassification.cs

Co-authored-by: Peter <34331512+pmaytak@users.noreply.github.com>

* Remove locales and update links to Microsoft Learn.

* Update src/client/Microsoft.Identity.Client/Kerberos/KerberosSupplementalTicketManager.cs

Co-authored-by: Gladwin Johnson <90415114+gladjohn@users.noreply.github.com>

* Update src/client/Microsoft.Identity.Client/Kerberos/KerberosSupplementalTicketManager.cs

Co-authored-by: Gladwin Johnson <90415114+gladjohn@users.noreply.github.com>

* Update InMemoryPartitionedCacheSerializer.cs

* MSDN redirect query string is not needed

* Update SECURITY.md

Co-authored-by: Gladwin Johnson <90415114+gladjohn@users.noreply.github.com>

* Update SECURITY.md

Co-authored-by: Gladwin Johnson <90415114+gladjohn@users.noreply.github.com>

---------

Co-authored-by: Peter <34331512+pmaytak@users.noreply.github.com>
Co-authored-by: Gladwin Johnson <90415114+gladjohn@users.noreply.github.com>

CHANGELOG.md

@@ -202,7 +202,7 @@ Resolved an issue where MSAL attempts to acquire a token via certificate authent
 - Added new APIs to acquire authentication data from WWW-Authenticate and Authentication-Info request headers. This will provide additional support for Proof-of-Possession. See [3026](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/issues/3026)
 
 ### Experimental Features
-- [Managed identities for Azure resources](https://learn.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/overview) provide Azure services with an automatically managed identity in Azure Active Directory. You can use this identity to authenticate to any service that supports Azure AD authentication, without having credentials in your code. MSAL now supports acquiring token for managed identities for Azure App Services and Azure Virtual Machines. Use `WithManagedIdentity()` method on the `AcquireTokenForClient` API to get an MSI token. This is an experimental feature and may change in the future versions of MSAL. See [3754](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/issues/3754) and [3829](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/issues/3829)
+- [Managed identities for Azure resources](https://learn.microsoft.com/azure/active-directory/managed-identities-azure-resources/overview) provide Azure services with an automatically managed identity in Azure Active Directory. You can use this identity to authenticate to any service that supports Azure AD authentication, without having credentials in your code. MSAL now supports acquiring token for managed identities for Azure App Services and Azure Virtual Machines. Use `WithManagedIdentity()` method on the `AcquireTokenForClient` API to get an MSI token. This is an experimental feature and may change in the future versions of MSAL. See [3754](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/issues/3754) and [3829](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/issues/3829)
 
 ### Supportability
 - Enabled more logging for new WAM broker. See [3575](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/issues/3575)
@@ -724,7 +724,7 @@ Logs are now consistent when you use several .NET authentication libraries from
 
 ### Fundamentals:
 **Added additional code analyzers**. See issue [#2419](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/issues/2419) for details.  
-**Improved documentation to support Android 11**. See [Xamarin Android 11](https://docs.microsoft.com/en-us/azure/active-directory/develop/msal-net-xamarin-android-considerations#android-11-support) docs.
+**Improved documentation to support Android 11**. See [Xamarin Android 11](https://learn.microsoft.com/entra/identity-platform/msal-net-xamarin-android-considerations#android-11-support) docs.
 
 4.27.0
 ==========
@@ -1189,7 +1189,7 @@ Bug Fixes:
 3.0.6-preview
 =============
 New Features:
-- **MSAL.NET now creates an HttpClient that uses the AndroidClientHandler** for Android 4.1 and higher. See [documentation for more information](https://docs.microsoft.com/en-us/xamarin/android/app-fundamentals/http-stack?tabs=windows). [MSAL issue #1076](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/issues/1076)
+- **MSAL.NET now creates an HttpClient that uses the AndroidClientHandler** for Android 4.1 and higher. See [documentation for more information](https://learn.microsoft.com/xamarin/android/app-fundamentals/http-stack?tabs=windows). [MSAL issue #1076](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/issues/1076)
 
 Bug Fixes:
 - **When doing the ADAL.NET fallback from MSAL.NET, MSAL.NET was doing the lookup based on the account.HomeAccountId or requestParameters.LoginHint**. In ADAL.NET an account will never have a HomeAccountId (by design), so lookup needs to happen by Account.UserName instead. [MSAL.NET issue #1100](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/issues/1100)

README.md

@@ -61,6 +61,6 @@ See the [our telemetry documentation](https://learn.microsoft.com/entra/msal/dot
 
 ## Trademarks
 
-This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow [Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general). Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.
+This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow [Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/legal/intellectualproperty/trademarks/usage/general). Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.
 
 Copyright © Microsoft Corporation. All rights reserved. Licensed under the MIT License (the "License").

SECURITY.md

@@ -4,15 +4,15 @@
 
 Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, which include [Microsoft](https://github.com/Microsoft), [Azure](https://github.com/Azure), [DotNet](https://github.com/dotnet), [AspNet](https://github.com/aspnet), [Xamarin](https://github.com/xamarin), and [our GitHub organizations](https://opensource.microsoft.com/).
 
-If you believe you have found a security vulnerability in any Microsoft-owned repository that meets Microsoft's [Microsoft's definition of a security vulnerability](https://docs.microsoft.com/en-us/previous-versions/tn-archive/cc751383(v=technet.10)), please report it to us as described below.
+If you believe you have found a security vulnerability in any Microsoft-owned repository that meets [Microsoft's definition of a security vulnerability](https://www.microsoft.com/msrc/definition-of-a-security-vulnerability), please report it to us as described below.
 
 ## Reporting Security Issues
 
 **Please do not report security vulnerabilities through public GitHub issues.**
 
 Instead, please report them to the Microsoft Security Response Center (MSRC) at [https://msrc.microsoft.com/create-report](https://msrc.microsoft.com/create-report).
 
-If you prefer to submit without logging in, send email to [secure@microsoft.com](mailto:secure@microsoft.com).  If possible, encrypt your message with our PGP key; please download it from the the [Microsoft Security Response Center PGP Key page](https://www.microsoft.com/en-us/msrc/pgp-key-msrc).
+If you prefer to submit without logging in, send email to [secure@microsoft.com](mailto:secure@microsoft.com). If possible, encrypt your message with our PGP key; please download it from the the [Microsoft Security Response Center PGP Key page](https://www.microsoft.com/msrc/pgp-key-msrc).
 
 You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Additional information can be found at [microsoft.com/msrc](https://www.microsoft.com/msrc).
 
@@ -36,6 +36,6 @@ We prefer all communications to be in English.
 
 ## Policy
 
-Microsoft follows the principle of [Coordinated Vulnerability Disclosure](https://www.microsoft.com/en-us/msrc/cvd).
+Microsoft follows the principle of [Coordinated Vulnerability Disclosure](https://www.microsoft.com/msrc/cvd).
 
 <!-- END MICROSOFT SECURITY.MD BLOCK -->

build/MSAL.CodeCoverage.runsettings

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="utf-8"?>  
 
 <!-- Customised run settings file to exclude test assemblies from coverage.
-    See https://msdn.microsoft.com/en-us/library/jj159530.aspx for more info. -->
+    See https://learn.microsoft.com/previous-versions/visualstudio/visual-studio-2015/test/customizing-code-coverage-analysis?view=vs-2015 for more info. -->
 
 <!-- File name extension must be .runsettings -->  
 <RunSettings>  
@@ -34,4 +34,3 @@ Included items must then not match any entries in the exclude list to remain inc
     </DataCollectors>  
   </DataCollectionRunSettings>  
 </RunSettings>  
-

build/installEdgeDriver.ps1

@@ -7,7 +7,7 @@ if ([string]::IsNullOrEmpty($edgeVersion)) {
     echo "##vso[task.complete result=Failed;]Failed"
     }
 
-$url = "https://msedgedriver.azureedge.net/$edgeVersion/edgedriver_win64.zip" #Edge Driver from https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/
+$url = "https://msedgedriver.azureedge.net/$edgeVersion/edgedriver_win64.zip" #Edge Driver from https://developer.microsoft.com/microsoft-edge/tools/webdriver/
 $fileName = "edgedriver_win64.zip"
 $source = "C:\Downloads\$fileName"
 $destination = "C:\Program Files\dotnet\"

build/win-installer-helper.psm1

@@ -2057,7 +2057,7 @@ function Get-PackageFullName
         Gets the latest installed version of the .NET Framework.
     .DESCRIPTION
         Retrieves information from the registry based on the documentation at this link:
-        https://docs.microsoft.com/en-us/dotnet/framework/migration-guide/how-to-determine-which-versions-are-installed#net_b.
+        https://learn.microsoft.com/dotnet/framework/migration-guide/how-to-determine-which-versions-are-installed#net_b.
         Returns the entire child object from the registry.
     .OUTPUTS
         The child registry entry for the .NET framework installation.

src/client/Microsoft.Identity.Client/ApiConfig/EmbeddedWebViewOptions.cs

@@ -41,7 +41,7 @@ internal static EmbeddedWebViewOptions GetDefaultOptions()
         /// <summary>
         /// It is possible for applications to bundle a fixed version of the runtime, and ship it side-by-side.
         /// For this you need to tell MSAL (so it can tell WebView2) where to find the runtime bits by setting this property. If you don't set it, MSAL will attempt to use a system-wide "evergreen" installation of the runtime."
-        /// For more details see: https://docs.microsoft.com/en-us/dotnet/api/microsoft.web.webview2.core.corewebview2environment.createasync?view=webview2-dotnet-1.0.705.50
+        /// For more details see <see href="https://learn.microsoft.com/dotnet/api/microsoft.web.webview2.core.corewebview2environment.createasync?view=webview2-dotnet-1.0.705.50">CoreWebView2Environment.CreateAsync Method</see>.
         /// </summary>
         [EditorBrowsable(EditorBrowsableState.Never)]
         [Obsolete("In case when WebView2 is not available, MSAL.NET will fallback to legacy WebView.", true)]

src/client/Microsoft.Identity.Client/ApiConfig/WindowsBrokerOptions.cs

@@ -52,7 +52,7 @@ internal static WindowsBrokerOptions CreateDefault()
         /// Display a custom text in the broker UI controls which support it. 
         /// </summary>
         /// <remarks>
-        /// Currently only the WAM account picker allows for this customization, see <see href="https://docs.microsoft.com/en-us/windows/uwp/security/web-account-manager#add-a-custom-header">WAM documentation</see>.
+        /// Currently only the WAM account picker allows for this customization, see <see href="https://learn.microsoft.com/windows/uwp/security/web-account-manager#add-a-custom-header">WAM documentation</see>.
         /// </remarks>
         public string HeaderText { get; set; }
 

src/client/Microsoft.Identity.Client/AppConfig/ConfidentialClientApplicationOptions.cs

@@ -22,7 +22,7 @@ public class ConfidentialClientApplicationOptions : ApplicationOptions
         /// "TryAutoDetect" and MSAL.NET will attempt to auto-detect the region. 
         /// </summary>
         /// <remarks>
-        /// Region names as per https://docs.microsoft.com/en-us/dotnet/api/microsoft.azure.management.resourcemanager.fluent.core.region?view=azure-dotnet.
+        /// Region names as per <see href="https://learn.microsoft.com/dotnet/api/microsoft.azure.management.resourcemanager.fluent.core.region?view=azure-dotnet-legacy">Region class documentation</see>.
         /// Not all auth flows can use the regional token service. 
         /// Service To Service (client credential flow) tokens can be obtained from the regional service.
         /// Requires configuration at the tenant level.

src/client/Microsoft.Identity.Client/AuthScheme/PoP/IPoPCryptoProvider.cs

@@ -31,8 +31,8 @@ public interface IPoPCryptoProvider
 
         /// <summary>
         /// Algorithm used to sign proof of possession request. 
-        /// See https://docs.microsoft.com/en-us/azure/key-vault/keys/about-keys#signverify for ECD
-        /// See https://docs.microsoft.com/en-us/azure/key-vault/keys/about-keys#signverify-1 for RSA
+        /// See <see href="https://learn.microsoft.com/azure/key-vault/keys/about-keys-details#signverify">EC algorithms</see> for ECD.
+        /// See <see href="https://learn.microsoft.com/azure/key-vault/keys/about-keys-details#signverify-1">RSA algorithms</see> for RSA.
         /// </summary>
         string CryptographicAlgorithm { get; }
 

src/client/Microsoft.Identity.Client/Extensibility/ICustomWebUI.cs

@@ -25,7 +25,7 @@ public interface ICustomWebUi
         /// will redirect to it.
         /// </param>
         /// <param name="cancellationToken">The cancellation token to which you should respond to.
-        /// See https://docs.microsoft.com/en-us/dotnet/standard/parallel-programming/task-cancellation for details.
+        /// See <see href="https://learn.microsoft.com/dotnet/standard/parallel-programming/task-cancellation">Task cancellation</see> for details.
         /// </param>
         /// <returns> The URI returned back from the STS authorization endpoint. This URI contains a code=CODE
         /// parameters that MSAL.NET will extract and redeem.

src/client/Microsoft.Identity.Client/Instance/Region/RegionManager.cs

@@ -31,7 +31,7 @@ public RegionInfo(string region, RegionAutodetectionSource regionSource, string
             public readonly string RegionDetails;
         }
 
-        // For information of the current api-version refer: https://docs.microsoft.com/en-us/azure/virtual-machines/windows/instance-metadata-service#versioning
+        // For information of the current api-version refer: https://learn.microsoft.com/azure/virtual-machines/instance-metadata-service?tabs=windows#versioning
         private const string ImdsEndpoint = "http://169.254.169.254/metadata/instance/compute/location";
         private const string DefaultApiVersion = "2020-06-01";
 

src/client/Microsoft.Identity.Client/Kerberos/KerberosSupplementalTicket.cs

@@ -75,7 +75,10 @@ public KerberosSupplementalTicket(string errorMessage)
             this.ErrorMessage = errorMessage;
         }
 
-        /// <inheritdoc/>
+        /// <summary>
+        /// Creates a string representation of the data captured in the Kerberos supplemental ticket.
+        /// </summary>
+        /// <returns>A string containing the realm, service principal name, client name, and key type.</returns>
         public override string ToString()
         {
             return $"[ Realm: {Realm}, sp: {ServicePrincipalName}, cn: {ClientName}, KeyType: {KeyType} ]";

src/client/Microsoft.Identity.Client/Kerberos/KerberosSupplementalTicketManager.cs

@@ -76,8 +76,9 @@ public static KerberosSupplementalTicket FromIdToken(string idToken)
         /// Save current Kerberos Ticket to current user's Ticket Cache.
         /// </summary>
         /// <param name="ticket">Kerberos ticket object to save.</param>
-        /// <remarks>Can throws <see cref="ArgumentException"/> when given ticket parameter is not a valid Kerberos Supplemental Ticket.
-        /// Can throws <see cref="Win32Exception"/> if error occurs while saving ticket information into Ticket Cache.
+        /// <remarks>Throws <see cref="ArgumentException"/> when given ticket parameter is not a valid Kerberos supplemental ticket.
+
+        /// Throws <see cref="Win32Exception"/> if error occurs while saving ticket information into Ticket Cache.
         /// </remarks>
         public static void SaveToWindowsTicketCache(KerberosSupplementalTicket ticket)
         {
@@ -90,8 +91,9 @@ public static void SaveToWindowsTicketCache(KerberosSupplementalTicket ticket)
         /// <param name="ticket">Kerberos ticket object to save.</param>
         /// <param name="logonId">The Logon Id of the user owning the ticket cache.
         /// The default of 0 represents the currently logged on user.</param>
-        /// <remarks>Can throw <see cref="ArgumentException"/> when given ticket parameter is not a valid Kerberos Supplemental Ticket.
-        /// Can throw <see cref="Win32Exception"/> if error occurs while saving ticket information into Ticket Cache.
+        /// <remarks>Throws <see cref="ArgumentException"/> when given ticket parameter is not a valid Kerberos supplemental ticket.
+
+        /// Throws <see cref="Win32Exception"/> if error occurs while saving ticket information into Ticket Cache.
         /// </remarks>
         public static void SaveToWindowsTicketCache(KerberosSupplementalTicket ticket, long logonId)
         {
@@ -124,7 +126,7 @@ public static void SaveToWindowsTicketCache(KerberosSupplementalTicket ticket, l
         /// <param name="servicePrincipalName">Service principal name to find associated Kerberos Ticket.</param>
         /// <returns>Byte stream of searched Kerberos Ticket information if exists. Null, otherwise.</returns>
         /// <remarks>
-        /// Can throws <see cref="Win32Exception"/> if error occurs while searching ticket information from Ticket Cache.
+        /// Throws <see cref="Win32Exception"/> if error occurs while searching ticket information from Ticket Cache.
         /// </remarks>
         public static byte[] GetKerberosTicketFromWindowsTicketCache(string servicePrincipalName)
         {
@@ -140,7 +142,7 @@ public static byte[] GetKerberosTicketFromWindowsTicketCache(string servicePrinc
         /// The default of 0 represents the currently logged on user.</param>
         /// <returns>Byte stream of searched Kerberos Ticket information if exists. Null, otherwise.</returns>
         /// <remarks>
-        /// Can throws <see cref="Win32Exception"/> if error occurs while searching ticket information from Ticket Cache.
+        /// Throws <see cref="Win32Exception"/> if error occurs while searching ticket information from Ticket Cache.
         /// </remarks>
         public static byte[] GetKerberosTicketFromWindowsTicketCache(string servicePrincipalName, long logonId)
         {

src/client/Microsoft.Identity.Client/Microsoft.Identity.Client.csproj

@@ -169,7 +169,7 @@
     <UseWindowsForms>true</UseWindowsForms>
     <!--
     MSAL will run on Windows 7 and 8 but requires to be built against Win10 to use WinRT APIs for WAM
-    See https://docs.microsoft.com/en-us/dotnet/standard/analyzers/platform-compat-analyzer and
+    See https://learn.microsoft.com/dotnet/standard/analyzers/platform-compat-analyzer and
     https://github.com/dotnet/designs/blob/main/accepted/2020/platform-checks/platform-checks.md for details
     -->
     <SupportedOSPlatformVersion>7.0</SupportedOSPlatformVersion>

src/client/Microsoft.Identity.Client/MigrationAid/TokenCache.MigrationAid.cs

@@ -239,7 +239,7 @@ public void Deserialize(byte[] msalV2State)
         /// </summary>
         /// <param name="args">Arguments related to the cache item impacted</param>
         [EditorBrowsable(EditorBrowsableState.Never)]
-        [Obsolete("Use Microsoft.Identity.Client.TokenCacheCallback instead. See https://aka.msa/msal-net-3x-cache-breaking-change", true)]
+        [Obsolete("Use Microsoft.Identity.Client.TokenCacheCallback instead. See https://aka.ms/msal-net-3x-cache-breaking-change", true)]
         public delegate void TokenCacheNotification(TokenCacheNotificationArgs args);
 
         /// <summary>