Fix XML comments for return values on IAuthorizationService

[Copilot]

The XML documentation for IAuthorizationService methods and their extension methods incorrectly described return values as boolean flags, when they actually return Task<AuthorizationResult>.

Before:

/// <returns>
/// A flag indicating whether authorization has succeeded.
/// This value is <c>true</c> when the user fulfills the policy; otherwise <c>false</c>.
/// </returns>

After:

/// <returns>
/// 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>

Changes:

• Updated XML documentation for 2 methods in IAuthorizationService.cs
• Updated XML documentation for 4 extension methods in AuthorizationServiceExtensions.cs
• Documentation now correctly references Task<AuthorizationResult> return type
• Added proper XML references to Task{TResult} and AuthorizationResult types
• Clarified that boolean success indication is available via AuthorizationResult.Succeeded property

The documentation now accurately reflects the actual return types and provides clear guidance on how to check authorization results.

Fixes #62764.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[dotnet-policy-service]

Greetings human! You've submitted a PR that modifies code that is shared with https://github.com/dotnet/runtime . Please make sure you synchronize this code with the changes in that repo!

[JamesNK]

@copilot Also update DefaultAuthorizationService

[Copilot]

@copilot Also update DefaultAuthorizationService

Updated DefaultAuthorizationService XML comments to match the corrected pattern (e5260c8). Both AuthorizeAsync methods now correctly describe their return values as Task instead of boolean flags.

[Copilot]

Pull Request Overview

This PR updates the XML <returns> documentation on IAuthorizationService methods and their extensions to accurately describe the Task<AuthorizationResult> return type and guide consumers to use the AuthorizationResult.Succeeded property for success checks.

• Corrected <returns> tags in the interface, default implementation, and extension methods
• Added <see> references for Task{TResult} and AuthorizationResult
• Clarified usage of AuthorizationResult.Succeeded instead of boolean return flags

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
src/Security/Authorization/Core/src/IAuthorizationService.cs	Updated <returns> doc on interface methods
src/Security/Authorization/Core/src/DefaultAuthorizationService.cs	Updated <returns> doc on implementation
src/Security/Authorization/Core/src/AuthorizationServiceExtensions.cs	Updated <returns> doc on extension methods

Comments suppressed due to low confidence (2)

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

• For clearer XML linkage, reference the concrete return type by using <see cref="Task{AuthorizationResult}"/> instead of the generic <see cref="Task{TResult}"/>.

    /// A <see cref="Task{TResult}"/> that contains an <see cref="AuthorizationResult"/> indicating whether authorization has succeeded.

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

• [nitpick] To reduce duplicated XML comments across multiple overloads, consider using <inheritdoc cref="IAuthorizationService.AuthorizeAsync(ClaimsPrincipal, object?, IAuthorizationRequirement)"/> (and equivalents) in each extension method.

    /// A <see cref="Task{TResult}"/> that contains an <see cref="AuthorizationResult"/> indicating whether requirement evaluation has succeeded or failed.