[fix-finder] Add XML documentation to `Android.Security.KeyChain` public methods

[github-actions]

Problem

The Android.Security.KeyChain partial class in src/Mono.Android/Android.Security/KeyChain.cs contains 5 public methods that lack XML documentation comments. These are .NET-specific convenience methods that bridge Android's KeyChain API to .NET's X509Certificate2 type — they're frequently used by developers implementing TLS client authentication and certificate selection, and their behavior is not obvious from the signatures alone.

Location

• File: src/Mono.Android/Android.Security/KeyChain.cs
• Lines: 11–85 (all public methods in the file)

Current Code

public static X509Certificate2? GetX509Certificate2WithPrivateKey (Android.Content.Context context, string alias)

[SupportedOSPlatform("android23.0")]
public static async Task<string?> ChoosePrivateKeyAliasAsync (
    Android.App.Activity activity, string[]? keyTypes,
    Java.Security.IPrincipal[]? issuers, Android.Net.Uri? uri, string? alias)

public static async Task<string?> ChoosePrivateKeyAliasAsync (
    Android.App.Activity activity, string[]? keyTypes,
    Java.Security.IPrincipal[]? issuers, string? host, int port, string? alias)

[SupportedOSPlatform("android23.0")]
public static async Task<X509Certificate2?> ChooseX509Certificate2WithPrivateKeyAsync (
    Android.App.Activity activity, string[]? keyTypes,
    Java.Security.IPrincipal[]? issuers, Android.Net.Uri? uri, string? alias)

public static async Task<X509Certificate2?> ChooseX509Certificate2WithPrivateKeyAsync (
    Android.App.Activity activity, string[]? keyTypes,
    Java.Security.IPrincipal[]? issuers, string? host, int port, string? alias)

Suggested Fix

Add <summary>, <param>, <returns>, and <remarks> XML doc comments to each public method. Example for the first method:

/// <summary>
/// Retrieves an <see cref="X509Certificate2"/> with its associated private key from the Android system KeyChain.
/// </summary>
/// <param name="context">The Android context used to access the KeyChain.</param>
/// <param name="alias">The alias of the private key and certificate chain to retrieve.</param>
/// <returns>
/// An <see cref="X509Certificate2"/> containing the certificate and private key,
/// or <see langword="null"/> if the private key or certificate chain is not available for the given alias.
/// </returns>
/// <remarks>
/// This method combines <see cref="KeyChain.GetPrivateKey"/> and <see cref="KeyChain.GetCertificateChain"/>
/// into a single call that returns a .NET <see cref="X509Certificate2"/> suitable for use with
/// <see cref="System.Net.Http.HttpClientHandler.ClientCertificates"/> or other TLS APIs.
/// </remarks>
public static X509Certificate2? GetX509Certificate2WithPrivateKey (Android.Content.Context context, string alias)

For the ChoosePrivateKeyAliasAsync methods, document that they display a system UI for the user to select a certificate and return the chosen alias (or null if cancelled). Reference the underlying KeyChain.ChoosePrivateKeyAlias Android API.

For the ChooseX509Certificate2WithPrivateKeyAsync methods, document that they combine the alias selection UI with GetX509Certificate2WithPrivateKey for a one-call TLS certificate workflow.

Guidelines

• Follow standard .NET XML documentation conventions (<summary>, <param>, <returns>, <remarks>)
• Use <see cref="..."/> for cross-references to types and methods
• Use <see langword="null"/> for null references
• Mention the [SupportedOSPlatform] requirement in remarks where applicable
• Keep the existing code formatting (tabs, Mono style with space before ()

Acceptance Criteria

• All 5 public methods in src/Mono.Android/Android.Security/KeyChain.cs have complete XML documentation
• Each method has at minimum <summary>, <param> (for all parameters), and <returns> tags
• <remarks> sections reference the underlying Android API and explain .NET-specific behavior
• No other code changes — documentation only
• No new warnings introduced

Generated by Nightly Fix Finder for issue #11352 · ● 3.5M · ◷

• expires on May 21, 2026, 10:13 PM UTC

[github-actions]

This issue is being closed as outdated. A newer issue has been created: #11365

View newer issue

---

This action was performed automatically by the Nightly Fix Finder workflow.