Refactor XML comments for clarity in Microsoft.IdentityModel.Protocol…

…s.OpenIdConnect (#2676) * Refactor XML comments for clarity in Microsoft.IdentityModel.Protocols.OpenIdConnect * Apply suggestion from review --------- Co-authored-by: joegoldman2 <147369450+joegoldman@users.noreply.github.com>
AzureAD · Jun 29, 2024 · ff1331b · ff1331b
1 parent 0c5172c
commit ff1331b
Show file tree

Hide file tree

Showing 13 changed files with 77 additions and 65 deletions.
diff --git a/src/Microsoft.IdentityModel.Protocols.OpenIdConnect/ActiveDirectoryOpenIdConnectEndpoints.cs b/src/Microsoft.IdentityModel.Protocols.OpenIdConnect/ActiveDirectoryOpenIdConnectEndpoints.cs
@@ -4,7 +4,7 @@
 namespace Microsoft.IdentityModel.Protocols.OpenIdConnect
 {
     /// <summary>
-    /// Well known endpoints for AzureActiveDirectory
+    /// Well-known endpoints for Microsoft Entra ID.
     /// </summary>
     public static class ActiveDirectoryOpenIdConnectEndpoints
     {

diff --git a/...dentityModel.Protocols.OpenIdConnect/Configuration/OpenIdConnectConfigurationRetriever.cs b/...dentityModel.Protocols.OpenIdConnect/Configuration/OpenIdConnectConfigurationRetriever.cs
@@ -11,7 +11,7 @@
 namespace Microsoft.IdentityModel.Protocols.OpenIdConnect
 {
     /// <summary>
-    ///  Retrieves a populated <see cref="OpenIdConnectConfiguration"/> given an address.
+    /// Retrieves a populated <see cref="OpenIdConnectConfiguration"/> given an address.
     /// </summary>
     public class OpenIdConnectConfigurationRetriever : IConfigurationRetriever<OpenIdConnectConfiguration>
     {

diff --git a/src/Microsoft.IdentityModel.Protocols.OpenIdConnect/OpenIdConnectGrantTypes.cs b/src/Microsoft.IdentityModel.Protocols.OpenIdConnect/OpenIdConnectGrantTypes.cs
@@ -4,15 +4,28 @@
 namespace Microsoft.IdentityModel.Protocols.OpenIdConnect
 {
     /// <summary>
-    /// Grant types for token requests. See https://datatracker.ietf.org/doc/html/rfc6749.
+    /// Defines grant types for token requests. See <see href="https://datatracker.ietf.org/doc/html/rfc6749"/>.
     /// </summary>
     public static class OpenIdConnectGrantTypes
     {
-#pragma warning disable 1591
+        /// <summary>
+        /// Indicates the 'authorization_code' grant type. See <see href="https://datatracker.ietf.org/doc/html/rfc6749#section-4.1"/>.
+        /// </summary>
         public const string AuthorizationCode = "authorization_code";
+
+        /// <summary>
+        /// Indicates the 'refresh_token' grant type. See <see href="https://datatracker.ietf.org/doc/html/rfc6749#section-6"/>.
+        /// </summary>
         public const string RefreshToken = "refresh_token";
+
+        /// <summary>
+        /// Indicates the 'password' grant type. See <see href="https://datatracker.ietf.org/doc/html/rfc6749#section-4.3"/>.
+        /// </summary>
         public const string Password = "password";
+
+        /// <summary>
+        /// Indicates the 'client_credentials' grant type. See <see href="https://datatracker.ietf.org/doc/html/rfc6749#section-4.4"/>.
+        /// </summary>
         public const string ClientCredentials = "client_credentials";
-#pragma warning restore 1591
     }
 }
diff --git a/src/Microsoft.IdentityModel.Protocols.OpenIdConnect/OpenIdConnectMessage.cs b/src/Microsoft.IdentityModel.Protocols.OpenIdConnect/OpenIdConnectMessage.cs
@@ -13,7 +13,7 @@
 namespace Microsoft.IdentityModel.Protocols.OpenIdConnect
 {
     /// <summary>
-    /// Provides access to common OpenIdConnect parameters.
+    /// Provides access to common OpenID Connect parameters.
     /// </summary>
     public class OpenIdConnectMessage : AuthenticationProtocolMessage
     {

diff --git a/src/Microsoft.IdentityModel.Protocols.OpenIdConnect/OpenIdConnectParameterNames.cs b/src/Microsoft.IdentityModel.Protocols.OpenIdConnect/OpenIdConnectParameterNames.cs
@@ -6,7 +6,7 @@
 namespace Microsoft.IdentityModel.Protocols.OpenIdConnect
 {
     /// <summary>
-    /// Parameter names for OpenIdConnect Request/Response messages.
+    /// Parameter names for OpenID Connect Request/Response messages.
     /// </summary>
     public static class OpenIdConnectParameterNames
     {

diff --git a/src/Microsoft.IdentityModel.Protocols.OpenIdConnect/OpenIdConnectPrompt.cs b/src/Microsoft.IdentityModel.Protocols.OpenIdConnect/OpenIdConnectPrompt.cs
@@ -4,32 +4,32 @@
 namespace Microsoft.IdentityModel.Protocols.OpenIdConnect
 {
     /// <summary>
-    /// Prompt types for OpenIdConnect.
+    /// Defines prompt types for OpenID Connect.
     /// </summary>
     public static class OpenIdConnectPrompt
     {
         /// <summary>
-        /// Indicates 'none' prompt type see: http://openid.net/specs/openid-connect-core-1_0.html#AuthRequest.
+        /// Indicates the 'none' prompt type. See <see href="https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest"/>.
         /// </summary>
         public const string None = "none";
 
         /// <summary>
-        /// Indicates 'create' prompt type see: https://openid.net/specs/openid-connect-prompt-create-1_0.html.
+        /// Indicates the 'create' prompt type. See <see href="https://openid.net/specs/openid-connect-prompt-create-1_0.html"/>.
         /// </summary>
         public const string Create = "create";
 
         /// <summary>
-        /// Indicates 'login' prompt type see: http://openid.net/specs/openid-connect-core-1_0.html#AuthRequest.
+        /// Indicates the 'login' prompt type. See <see href="https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest"/>.
         /// </summary>
         public const string Login = "login";
 
         /// <summary>
-        /// Indicates 'consent' prompt type see: http://openid.net/specs/openid-connect-core-1_0.html#AuthRequest.
+        /// Indicates the 'consent' prompt type. See <see href="https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest"/>.
         /// </summary>
         public const string Consent = "consent";
 
         /// <summary>
-        /// Indicates 'select_account' prompt type see: http://openid.net/specs/openid-connect-core-1_0.html#AuthRequest.
+        /// Indicates the 'select_account' prompt type. See <see href="https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest"/>.
         /// </summary>
         public const string SelectAccount = "select_account";
     }

diff --git a/...Microsoft.IdentityModel.Protocols.OpenIdConnect/OpenIdConnectProtocolValidationContext.cs b/...Microsoft.IdentityModel.Protocols.OpenIdConnect/OpenIdConnectProtocolValidationContext.cs
@@ -8,7 +8,7 @@ namespace Microsoft.IdentityModel.Protocols.OpenIdConnect
 {
     /// <summary>
     /// A context that is used by a <see cref="OpenIdConnectProtocolValidator"/> when validating an OpenIdConnect Response
-    /// to ensure it compliant with http://openid.net/specs/openid-connect-core-1_0.html.
+    /// to ensure it's compliant with <see href="https://openid.net/specs/openid-connect-core-1_0.html"/>.
     /// </summary>
     public class OpenIdConnectProtocolValidationContext
     {

diff --git a/src/Microsoft.IdentityModel.Protocols.OpenIdConnect/OpenIdConnectRequestType.cs b/src/Microsoft.IdentityModel.Protocols.OpenIdConnect/OpenIdConnectRequestType.cs
@@ -4,25 +4,25 @@
 namespace Microsoft.IdentityModel.Protocols.OpenIdConnect
 {
     /// <summary>
-    /// RequestTypes for OpenIdConnect.
+    /// Defines request types for OpenID Connect.
     /// </summary>
-    /// <remarks>Can be used to determine the message type by consumers of an <see cref="OpenIdConnectMessage"/>.
-    /// For example: <see cref="OpenIdConnectMessage.CreateAuthenticationRequestUrl"/> sets <see cref="OpenIdConnectMessage.RequestType"/>
-    /// to <see cref="OpenIdConnectRequestType.Authentication"/>.</remarks>
+    /// <remarks>
+    /// Can be used to determine the message type in an <see cref="OpenIdConnectMessage"/>.
+    /// </remarks>
     public enum OpenIdConnectRequestType
     {
         /// <summary>
-        /// Indicates an Authentication Request see: http://openid.net/specs/openid-connect-core-1_0.html#AuthRequest.
+        /// Indicates an Authentication Request. See <see href="https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest"/>.
         /// </summary>
         Authentication,
 
         /// <summary>
-        /// Indicates a Logout Request see: http://openid.net/specs/openid-connect-frontchannel-1_0.html#RPLogout.
+        /// Indicates a Logout Request. See <see href="https://openid.net/specs/openid-connect-frontchannel-1_0.html#RPLogout"/>.
         /// </summary>
         Logout,
 
         /// <summary>
-        /// Indicates a Token Request see: http://openid.net/specs/openid-connect-core-1_0.html#TokenRequest.
+        /// Indicates a Token Request. See <see href="https://openid.net/specs/openid-connect-core-1_0.html#TokenRequest"/>.
         /// </summary>
         Token,
     }

diff --git a/src/Microsoft.IdentityModel.Protocols.OpenIdConnect/OpenIdConnectResponseMode.cs b/src/Microsoft.IdentityModel.Protocols.OpenIdConnect/OpenIdConnectResponseMode.cs
@@ -4,25 +4,25 @@
 namespace Microsoft.IdentityModel.Protocols.OpenIdConnect
 {
     /// <summary>
-    /// Response modes for OpenIdConnect.
+    /// Defines response modes for OpenID Connect.
     /// </summary>
-    /// <remarks>Can be used to determine the response mode by consumers of an <see cref="OpenIdConnectMessage"/>.
-    /// For example: OpenIdConnectMessageTests.Publics() sets <see cref="OpenIdConnectMessage.ResponseMode"/>
-    /// to <see cref="OpenIdConnectResponseMode.FormPost"/>.</remarks>
+    /// <remarks>
+    /// Can be used to determine the response mode in an <see cref="OpenIdConnectMessage"/>.
+    /// </remarks>
     public static class OpenIdConnectResponseMode
     {
         /// <summary>
-        /// Indicates a Query Response see: http://openid.net/specs/openid-connect-core-1_0.html#ImplicitAuthResponse.
+        /// Indicates a Query Response. See <see href="https://openid.net/specs/oauth-v2-multiple-response-types-1_0.html"/>.
         /// </summary>
         public const string Query = "query";
 
         /// <summary>
-        /// Indicates a Form Post Response see: http://openid.net/specs/openid-connect-core-1_0.html#ImplicitAuthResponse.
+        /// Indicates a Form Post Response. See <see href="https://openid.net/specs/oauth-v2-form-post-response-mode-1_0.html"/>.
         /// </summary>
         public const string FormPost = "form_post";
 
         /// <summary>
-        /// Indicates a Fragment Response see: http://openid.net/specs/openid-connect-core-1_0.html#ImplicitAuthResponse.
+        /// Indicates a Fragment Response. See <see href="https://openid.net/specs/oauth-v2-multiple-response-types-1_0.html"/>.
         /// </summary>
         public const string Fragment = "fragment";
     }

diff --git a/src/Microsoft.IdentityModel.Protocols.OpenIdConnect/OpenIdConnectResponseType.cs b/src/Microsoft.IdentityModel.Protocols.OpenIdConnect/OpenIdConnectResponseType.cs
@@ -4,58 +4,58 @@
 namespace Microsoft.IdentityModel.Protocols.OpenIdConnect
 {
     /// <summary>
-    /// Response types for OpenIdConnect.
+    /// Defines response types for OpenID Connect.
     /// </summary>
-    /// <remarks>Can be used to determine the message type by consumers of an <see cref="OpenIdConnectMessage"/>.
-    /// For example: OpenIdConnectMessageTests.Publics() sets <see cref="OpenIdConnectMessage.ResponseType"/>
-    /// to <see cref="OpenIdConnectResponseType.CodeIdToken"/>.</remarks>
+    /// <remarks>
+    /// Can be used to determine the message type in an <see cref="OpenIdConnectMessage"/>.
+    /// </remarks>
     public static class OpenIdConnectResponseType
     {
         /// <summary>
-        /// Indicates 'code' type see: http://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth.
-        /// For Example: http://openid.net/specs/openid-connect-core-1_0.html#codeExample.
+        /// Indicates the 'code' response type. See <see href="https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth"/>.
+        /// For example: <see href="https://openid.net/specs/openid-connect-core-1_0.html#codeExample"/>.
         /// </summary>
         public const string Code = "code";
 
         /// <summary>
-        /// Indicates 'code id_token' type see: http://openid.net/specs/openid-connect-core-1_0.html#HybridAuthRequest.
-        /// For Example: http://openid.net/specs/openid-connect-core-1_0.html#code-id_tokenExample.
+        /// Indicates the 'code id_token' response type. See <see href="https://openid.net/specs/openid-connect-core-1_0.html#HybridAuthRequest"/>.
+        /// For example: <see href="https://openid.net/specs/openid-connect-core-1_0.html#code-id_tokenExample"/>.
         /// </summary>
         public const string CodeIdToken = "code id_token";
 
         /// <summary>
-        /// Indicates 'code id_token token' type see: http://openid.net/specs/openid-connect-core-1_0.html#HybridAuthRequest.
-        /// For Example: http://openid.net/specs/openid-connect-core-1_0.html#code-id_token-tokenExample.
+        /// Indicates the 'code id_token token' response type. See <see href="https://openid.net/specs/openid-connect-core-1_0.html#HybridAuthRequest"/>.
+        /// For example: <see href="https://openid.net/specs/openid-connect-core-1_0.html#code-id_token-tokenExample"/>.
         /// </summary>
         public const string CodeIdTokenToken = "code id_token token";
 
         /// <summary>
-        /// Indicates 'code token' type see: http://openid.net/specs/openid-connect-core-1_0.html#HybridAuthRequest.
-        /// For Example: http://openid.net/specs/openid-connect-core-1_0.html#code-tokenExample.
+        /// Indicates the 'code token' response type. See <see href="https://openid.net/specs/openid-connect-core-1_0.html#HybridAuthRequest"/>.
+        /// For example: <see href="https://openid.net/specs/openid-connect-core-1_0.html#code-tokenExample"/>.
         /// </summary>
         public const string CodeToken = "code token";
 
         /// <summary>
-        /// Indicates 'id_token' type see: http://openid.net/specs/openid-connect-core-1_0.html#HybridAuthRequest.
-        /// For Example: http://openid.net/specs/openid-connect-core-1_0.html#id_tokenExample.
+        /// Indicates the 'id_token' response type. See <see href="https://openid.net/specs/openid-connect-core-1_0.html#HybridAuthRequest"/>.
+        /// For example: <see href="https://openid.net/specs/openid-connect-core-1_0.html#id_tokenExample"/>.
         /// </summary>
         public const string IdToken = "id_token";
 
         /// <summary>
-        /// Indicates 'id_token token' type see: http://openid.net/specs/openid-connect-core-1_0.html#ImplicitFlowAuth.
-        /// For Example: http://openid.net/specs/openid-connect-core-1_0.html#id_token-tokenExample.
+        /// Indicates the 'id_token token' response type. See <see href="https://openid.net/specs/openid-connect-core-1_0.html#ImplicitFlowAuth"/>.
+        /// For example: <see href="https://openid.net/specs/openid-connect-core-1_0.html#id_token-tokenExample"/>.
         /// </summary>
         public const string IdTokenToken = "id_token token";
 
         /// <summary>
-        /// Defined in OAuth v2 multiple response types 1.0 spec, included for completion.
-        /// See: http://openid.net/specs/oauth-v2-multiple-response-types-1_0.html#OAuthResponseTypesReg.
+        /// Defined in the OAuth v2 Multiple Response Types 1.0 spec for completeness.
+        /// See: <see href="https://openid.net/specs/oauth-v2-multiple-response-types-1_0.html#OAuthResponseTypesReg"/>.
         /// </summary>
         public const string None = "none";
 
         /// <summary>
-        /// Defined in OAuth 2.0 spec, included for completion.
-        /// See: https://datatracker.ietf.org/doc/html/rfc6749#section-11.3.2.
+        /// Defined in the OAuth 2.0 spec for completeness.
+        /// See: <see href="https://datatracker.ietf.org/doc/html/rfc6749#section-11.3.2"/>.
         /// </summary>
         public const string Token = "token";
     }

diff --git a/src/Microsoft.IdentityModel.Protocols.OpenIdConnect/OpenIdConnectScope.cs b/src/Microsoft.IdentityModel.Protocols.OpenIdConnect/OpenIdConnectScope.cs
@@ -4,50 +4,50 @@
 namespace Microsoft.IdentityModel.Protocols.OpenIdConnect
 {
     /// <summary>
-    /// Specific scope values that are interesting to OpenID Connect.  See https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims
+    /// Defines scopes for OpenID Connect. For details, see <see href="https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims"/>.
     /// </summary>
-    /// <remarks>Can be used to determine the scope by consumers of an <see cref="OpenIdConnectMessage"/>.
-    /// For example: OpenIdConnectMessageTests.Publics() sets <see cref="OpenIdConnectMessage.Scope"/>
-    /// to <see cref="OpenIdConnectScope.OpenIdProfile"/>.</remarks>
+    /// <remarks>
+    /// Can be used to determine the scope in an <see cref="OpenIdConnectMessage"/>.
+    /// </remarks>
     public static class OpenIdConnectScope
     {
         /// <summary>
-        /// Indicates <c>address</c> scope see: https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims.
+        /// Indicates the <c>address</c> scope. See <see href="https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims"/>.
         /// </summary>
         public const string Address = "address";
 
         /// <summary>
-        /// Indicates <c>email</c> scope see: https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims.
+        /// Indicates the <c>email</c> scope. See <see href="https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims"/>.
         /// </summary>
         public const string Email = "email";
 
         /// <summary>
-        /// Indicates <c>offline_access</c> scope see: https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims.
+        /// Indicates the <c>offline_access</c> scope. See <see href="https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims"/>.
         /// </summary>
         public const string OfflineAccess = "offline_access";
 
         /// <summary>
-        /// Indicates <c>openid</c> scope see: https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims.
+        /// Indicates the <c>openid</c> scope. See <see href="https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims"/>.
         /// </summary>
         public const string OpenId = "openid";
 
         /// <summary>
-        /// Indicates <c>openid</c> and <c>profile</c> scope see: https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims.
+        /// Indicates both <c>openid</c> and <c>profile</c> scopes. See <see href="https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims"/>.
         /// </summary>
         public const string OpenIdProfile = "openid profile";
 
         /// <summary>
-        /// Indicates <c>phone</c> scope see: https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims.
+        /// Indicates the <c>phone</c> scope. See <see href="https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims"/>.
         /// </summary>
         public const string Phone = "phone";
 
         /// <summary>
-        /// Indicates <c>profile</c> scope see: https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims.
+        /// Indicates the <c>profile</c> scope. See <see href="https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims"/>.
         /// </summary>
         public const string Profile = "profile";
 
         /// <summary>
-        /// Indicates <c>user_impersonation</c> scope for Azure Active Directory.
+        /// Indicates the <c>user_impersonation</c> scope for Microsoft Entra ID.
         /// </summary>
         public const string UserImpersonation = "user_impersonation";
     }

diff --git a/src/Microsoft.IdentityModel.Protocols.OpenIdConnect/OpenIdConnectSessionProperties.cs b/src/Microsoft.IdentityModel.Protocols.OpenIdConnect/OpenIdConnectSessionProperties.cs
@@ -4,15 +4,15 @@
 namespace Microsoft.IdentityModel.Protocols.OpenIdConnect
 {
     /// <summary>
-    /// Defines a set of properties names 
+    /// Defines a set of properties names.
     /// </summary>
     public static class OpenIdConnectSessionProperties
     {
         /// <summary>
         /// Property defined for 'check_session_iframe'.
         /// </summary>
         public const string CheckSessionIFrame = ".checkSessionIFrame";
-   
+
         /// <summary>
         /// Property defined for 'redirect_uri' set in the request for a 'code'
         /// </summary>
@@ -22,6 +22,5 @@ public static class OpenIdConnectSessionProperties
         /// Property defined for 'session state'
         /// </summary>
         public const string SessionState = ".sessionState";
-
     }
 }
diff --git a/src/Microsoft.IdentityModel.Protocols.OpenIdConnect/OpenIdProviderMetadataNames.cs b/src/Microsoft.IdentityModel.Protocols.OpenIdConnect/OpenIdProviderMetadataNames.cs
@@ -6,8 +6,8 @@
 namespace Microsoft.IdentityModel.Protocols.OpenIdConnect
 {
     /// <summary>
-    /// OpenId Provider Metadata parameter names
-    /// http://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata 
+    /// OpenID Provider Metadata parameter names
+    /// <see href="https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata"/>.
     /// </summary>
     public static class OpenIdProviderMetadataNames
     {