Fix XML comments for return values on IAuthorizationService (#62765)

Co-authored-by: James Newton-King <[email protected]>

Author: Copilot

src/Security/Authorization/Core/src/AuthorizationServiceExtensions.cs

@@ -21,8 +21,8 @@ public static class AuthorizationServiceExtensions
     /// <param name="resource">The resource to evaluate the policy against.</param>
     /// <param name="requirement">The requirement to evaluate the policy against.</param>
     /// <returns>
-    /// A flag indicating whether requirement evaluation has succeeded or failed.
-    /// This value is <c>true</c> when the user fulfills the policy, otherwise <c>false</c>.
+    /// A <see cref="Task{TResult}"/> that contains an <see cref="AuthorizationResult"/> indicating whether requirement evaluation has succeeded or failed.
+    /// The result's <see cref="AuthorizationResult.Succeeded"/> property is <c>true</c> when the user fulfills the policy; otherwise <c>false</c>.
     /// </returns>
     public static Task<AuthorizationResult> AuthorizeAsync(this IAuthorizationService service, ClaimsPrincipal user, object? resource, IAuthorizationRequirement requirement)
     {
@@ -40,8 +40,8 @@ public static Task<AuthorizationResult> AuthorizeAsync(this IAuthorizationServic
     /// <param name="resource">The resource to evaluate the policy against.</param>
     /// <param name="policy">The policy to evaluate.</param>
     /// <returns>
-    /// A flag indicating whether policy evaluation has succeeded or failed.
-    /// This value is <c>true</c> when the user fulfills the policy, otherwise <c>false</c>.
+    /// A <see cref="Task{TResult}"/> that contains an <see cref="AuthorizationResult"/> indicating whether policy evaluation has succeeded or failed.
+    /// The result's <see cref="AuthorizationResult.Succeeded"/> property is <c>true</c> when the user fulfills the policy; otherwise <c>false</c>.
     /// </returns>
     public static Task<AuthorizationResult> AuthorizeAsync(this IAuthorizationService service, ClaimsPrincipal user, object? resource, AuthorizationPolicy policy)
     {
@@ -58,8 +58,8 @@ public static Task<AuthorizationResult> AuthorizeAsync(this IAuthorizationServic
     /// <param name="user">The user to evaluate the policy against.</param>
     /// <param name="policy">The policy to evaluate.</param>
     /// <returns>
-    /// A flag indicating whether policy evaluation has succeeded or failed.
-    /// This value is <c>true</c> when the user fulfills the policy, otherwise <c>false</c>.
+    /// A <see cref="Task{TResult}"/> that contains an <see cref="AuthorizationResult"/> indicating whether policy evaluation has succeeded or failed.
+    /// The result's <see cref="AuthorizationResult.Succeeded"/> property is <c>true</c> when the user fulfills the policy; otherwise <c>false</c>.
     /// </returns>
     public static Task<AuthorizationResult> AuthorizeAsync(this IAuthorizationService service, ClaimsPrincipal user, AuthorizationPolicy policy)
     {
@@ -76,8 +76,8 @@ public static Task<AuthorizationResult> AuthorizeAsync(this IAuthorizationServic
     /// <param name="user">The user to evaluate the policy against.</param>
     /// <param name="policyName">The name of the policy to evaluate.</param>
     /// <returns>
-    /// A flag indicating whether policy evaluation has succeeded or failed.
-    /// This value is <c>true</c> when the user fulfills the policy, otherwise <c>false</c>.
+    /// A <see cref="Task{TResult}"/> that contains an <see cref="AuthorizationResult"/> indicating whether policy evaluation has succeeded or failed.
+    /// The result's <see cref="AuthorizationResult.Succeeded"/> property is <c>true</c> when the user fulfills the policy; otherwise <c>false</c>.
     /// </returns>
     public static Task<AuthorizationResult> AuthorizeAsync(this IAuthorizationService service, ClaimsPrincipal user, string policyName)
     {

src/Security/Authorization/Core/src/DefaultAuthorizationService.cs

@@ -56,8 +56,8 @@ public DefaultAuthorizationService(IAuthorizationPolicyProvider policyProvider,
     /// <param name="resource">The resource to evaluate the requirements against.</param>
     /// <param name="requirements">The requirements to evaluate.</param>
     /// <returns>
-    /// A flag indicating whether authorization has succeeded.
-    /// This value is <c>true</c> when the user fulfills the policy, otherwise <c>false</c>.
+    /// A <see cref="Task{TResult}"/> that contains an <see cref="AuthorizationResult"/> indicating whether authorization has succeeded.
+    /// The result's <see cref="AuthorizationResult.Succeeded"/> property is <c>true</c> when the user fulfills the policy; otherwise <c>false</c>.
     /// </returns>
     public virtual async Task<AuthorizationResult> AuthorizeAsync(ClaimsPrincipal user, object? resource, IEnumerable<IAuthorizationRequirement> requirements)
     {
@@ -93,8 +93,8 @@ public virtual async Task<AuthorizationResult> AuthorizeAsync(ClaimsPrincipal us
     /// <param name="resource">The resource the policy should be checked with.</param>
     /// <param name="policyName">The name of the policy to check against a specific context.</param>
     /// <returns>
-    /// A flag indicating whether authorization has succeeded.
-    /// This value is <c>true</c> when the user fulfills the policy otherwise <c>false</c>.
+    /// A <see cref="Task{TResult}"/> that contains an <see cref="AuthorizationResult"/> indicating whether authorization has succeeded.
+    /// The result's <see cref="AuthorizationResult.Succeeded"/> property is <c>true</c> when the user fulfills the policy; otherwise <c>false</c>.
     /// </returns>
     public virtual async Task<AuthorizationResult> AuthorizeAsync(ClaimsPrincipal user, object? resource, string policyName)
     {

src/Security/Authorization/Core/src/IAuthorizationService.cs

@@ -22,8 +22,8 @@ public interface IAuthorizationService
     /// </param>
     /// <param name="requirements">The requirements to evaluate.</param>
     /// <returns>
-    /// A flag indicating whether authorization has succeeded.
-    /// This value is <c>true</c> when the user fulfills the policy; otherwise <c>false</c>.
+    /// A <see cref="Task{TResult}"/> that contains an <see cref="AuthorizationResult"/> indicating whether authorization has succeeded.
+    /// The result's <see cref="AuthorizationResult.Succeeded"/> property is <c>true</c> when the user fulfills the policy; otherwise <c>false</c>.
     /// </returns>
     /// <remarks>
     /// Resource is an optional parameter and may be null. Please ensure that you check it is not
@@ -41,9 +41,8 @@ public interface IAuthorizationService
     /// </param>
     /// <param name="policyName">The name of the policy to check against a specific context.</param>
     /// <returns>
-    /// A flag indicating whether authorization has succeeded.
-    /// Returns a flag indicating whether the user, and optional resource has fulfilled the policy.
-    /// <c>true</c> when the policy has been fulfilled; otherwise <c>false</c>.
+    /// A <see cref="Task{TResult}"/> that contains an <see cref="AuthorizationResult"/> indicating whether authorization has succeeded.
+    /// The result's <see cref="AuthorizationResult.Succeeded"/> property is <c>true</c> when the policy has been fulfilled; otherwise <c>false</c>.
     /// </returns>
     /// <remarks>
     /// Resource is an optional parameter and may be null. Please ensure that you check it is not