Document .NET public API surface (#211)

* fix: document public API surface

* fix: clarify nullable feature flag docs

* docs: clarify group collection changeset

* test: cover group collection key semantics

Author: marandaneto

.changeset/gentle-ducks-share.md

@@ -0,0 +1,7 @@
+---
+"PostHog": patch
+"PostHog.AspNetCore": patch
+"PostHog.AI": patch
+---
+
+Document public APIs and make `GroupCollection.TryAdd(Group)` store entries by group type instead of group key, matching the collection's one-group-per-type behavior.

src/PostHog.AI/PostHogAIContext.cs

@@ -97,6 +97,11 @@ private PostHogAIContext(
     /// <param name="groups">Optional groups to associate with events.</param>
     /// <param name="privacyMode">Optional flag to enable/disable privacy mode.</param>
     /// <returns>An <see cref="IDisposable"/> that ends the scope when disposed.</returns>
+    /// <remarks>
+    /// Context is stored in <see cref="AsyncLocal{T}"/> and flows with asynchronous execution. Nested scopes inherit
+    /// parent values for any null arguments. Parent and child property/group dictionaries are merged, with child values
+    /// overriding parent values for duplicate keys. Disposing the returned object restores the previous context.
+    /// </remarks>
     public static IDisposable BeginScope(
         string? distinctId = null,
         string? traceId = null,

src/PostHog.AI/PostHogAIExtensions.cs

@@ -33,12 +33,14 @@ public static IHttpClientBuilder AddPostHogOpenAIHandler(this IHttpClientBuilder
 
     /// <summary>
     /// Adds an <see cref="OpenAIClient"/> that intercepts requests and sends events to PostHog.
-    /// Note: This will override the <see cref="OpenAIClientOptions.Transport"/> property to use the PostHog handler.
+    /// Note: This sets the <c>OpenAIClientOptions.Transport</c> property to use the PostHog handler and throws if a custom transport is already configured.
     /// </summary>
     /// <param name="services">The <see cref="IServiceCollection"/>.</param>
     /// <param name="apiKey">The OpenAI API key.</param>
     /// <param name="configureOptions">Optional action to configure <see cref="OpenAIClientOptions"/>.</param>
     /// <returns>The <see cref="IHttpClientBuilder"/> for the underlying HttpClient, allowing further customization (e.g. resilience).</returns>
+    /// <exception cref="ArgumentException">Thrown when <paramref name="apiKey"/> is null, empty, or whitespace.</exception>
+    /// <exception cref="InvalidOperationException">Thrown when PostHog services are not registered or when <paramref name="configureOptions"/> sets a custom transport.</exception>
     public static IHttpClientBuilder AddPostHogOpenAIClient(
         this IServiceCollection services,
         string apiKey,

src/PostHog.AI/PostHogOpenAIHandler.cs

@@ -15,12 +15,18 @@ public class PostHogOpenAIHandler : DelegatingHandler
     private readonly IPostHogClient _postHogClient;
     private readonly ILogger<PostHogOpenAIHandler> _logger;
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="PostHogOpenAIHandler"/> class.
+    /// </summary>
+    /// <param name="postHogClient">The PostHog client used to capture AI observability events.</param>
+    /// <param name="logger">The logger used to report capture failures.</param>
     public PostHogOpenAIHandler(IPostHogClient postHogClient, ILogger<PostHogOpenAIHandler> logger)
     {
         _postHogClient = postHogClient ?? throw new ArgumentNullException(nameof(postHogClient));
         _logger = logger ?? throw new ArgumentNullException(nameof(logger));
     }
 
+    /// <inheritdoc />
     protected override async Task<HttpResponseMessage> SendAsync(
         HttpRequestMessage request,
         CancellationToken cancellationToken

src/PostHog.AspNetCore/Cache/HttpContextFeatureFlagCache.cs

@@ -11,14 +11,16 @@ namespace PostHog.Cache;
 /// An implementation of <see cref="IFeatureFlagCache"/> that uses the current <see cref="HttpContext"/> to cache
 /// feature flags. If the <see cref="HttpContext"/> is not available, then the feature flags are not cached.
 /// </summary>
+/// <param name="httpContextAccessor">Accessor for the current <see cref="HttpContext"/>.</param>
+/// <param name="logger">Logger used to report cache hits, misses, and cache access failures.</param>
 public class HttpContextFeatureFlagCache(
     IHttpContextAccessor httpContextAccessor,
     ILogger<HttpContextFeatureFlagCache> logger) : IFeatureFlagCache
 {
     /// <summary>
     /// Constructs a new instance of <see cref="HttpContextFeatureFlagCache"/> without a logger.
     /// </summary>
-    /// <param name="httpContextAccessor"></param>
+    /// <param name="httpContextAccessor">Accessor for the current <see cref="HttpContext"/>.</param>
     public HttpContextFeatureFlagCache(IHttpContextAccessor httpContextAccessor)
         : this(httpContextAccessor, NullLogger<HttpContextFeatureFlagCache>.Instance)
     {

src/PostHog.AspNetCore/Config/IPostHogAspNetCoreConfigurationBuilder.cs

@@ -7,5 +7,8 @@ namespace PostHog.Config;
 /// </summary>
 public interface IPostHogAspNetCoreConfigurationBuilder : IPostHogConfigurationBuilder
 {
+    /// <summary>
+    /// Gets the ASP.NET Core application configuration.
+    /// </summary>
     public IConfiguration Configuration { get; }
 }

src/PostHog.AspNetCore/Config/PostHogConfigurationBuilderExtensions.cs

@@ -38,6 +38,7 @@ public static IPostHogConfigurationBuilder UseAspNetCore(this IPostHogConfigurat
     /// person properties and groups when evaluating feature flags. There's a base implementation of
     /// <see cref="PostHogFeatureFlagContextProvider"/> you can override.
     /// </remarks>
+    /// <typeparam name="TContextProvider">The context provider type used to supply feature flag evaluation context.</typeparam>
     /// <param name="builder">The <see cref="IPostHogConfigurationBuilder"/>.</param>
     /// <returns>The passed in <see cref="IPostHogConfigurationBuilder"/>.</returns>
     public static IPostHogConfigurationBuilder UseFeatureManagement<TContextProvider>(this IPostHogConfigurationBuilder builder)
@@ -54,6 +55,7 @@ public static IPostHogConfigurationBuilder UseFeatureManagement<TContextProvider
     /// <see cref="PostHogFeatureFlagContextProvider"/> you can override.
     /// </remarks>
     /// <param name="builder">The <see cref="IPostHogConfigurationBuilder"/>.</param>
+    /// <typeparam name="TContextProvider">The context provider type used to supply feature flag evaluation context.</typeparam>
     /// <param name="configure">
     /// Action used to configure the <see cref="IFeatureManagementBuilder"/>. Use this to provide a custom
     /// <see cref="ITargetingContextAccessor"/>.

src/PostHog.AspNetCore/FeatureManagement/PostHogFeatureDefinitionProvider.cs

@@ -9,6 +9,7 @@ namespace PostHog.FeatureManagement;
 /// <param name="posthog">The <see cref="IPostHogClient"/> used to evaluate feature flags.</param>
 public class PostHogFeatureDefinitionProvider(IPostHogClient posthog) : IFeatureDefinitionProvider
 {
+    /// <inheritdoc />
     public async Task<FeatureDefinition?> GetFeatureDefinitionAsync(string featureName)
     {
         await foreach (var feature in GetAllFeatureDefinitionsAsync())
@@ -21,6 +22,7 @@ public class PostHogFeatureDefinitionProvider(IPostHogClient posthog) : IFeature
         return null;
     }
 
+    /// <inheritdoc />
     public async IAsyncEnumerable<FeatureDefinition> GetAllFeatureDefinitionsAsync()
     {
         var localEvaluator = await posthog.GetLocalEvaluatorAsync(CancellationToken.None);

src/PostHog.AspNetCore/FeatureManagement/PostHogFeatureFilter.cs

@@ -7,6 +7,7 @@ namespace PostHog.FeatureManagement;
 /// PostHog <see cref="IFeatureFilter"/> that uses PostHog's API to check if a feature is enabled for the current user.
 /// </summary>
 /// <param name="variantFeatureManager">The <see cref="IVariantFeatureManager"/> we'll use to evaluate the flag.</param>
+/// <param name="logger">The logger used to report registration problems.</param>
 [FilterAlias("PostHog")]
 public class PostHogFeatureFilter(IVariantFeatureManager variantFeatureManager, ILogger<PostHogFeatureFilter> logger)
     : IFeatureFilter

src/PostHog.AspNetCore/FeatureManagement/PostHogVariantFeatureManager.cs

@@ -11,12 +11,14 @@ namespace PostHog.FeatureManagement;
 /// </summary>
 /// <param name="posthog">The <see cref="IPostHogClient"/> used to evaluate feature flags.</param>
 /// <param name="targetingContextAccessor">The <see cref="ITargetingContextAccessor" /> used to evaluate feature flags.</param>
+/// <param name="logger">The logger used to report registration problems.</param>
 public class PostHogVariantFeatureManager(
     IPostHogClient posthog,
     ITargetingContextAccessor targetingContextAccessor,
     ILogger<PostHogVariantFeatureManager> logger)
     : IVariantFeatureManager
 {
+    /// <inheritdoc />
     public async IAsyncEnumerable<string> GetFeatureNamesAsync(
         [EnumeratorCancellation] CancellationToken cancellationToken = new())
     {
@@ -31,13 +33,15 @@ public async IAsyncEnumerable<string> GetFeatureNamesAsync(
         }
     }
 
+    /// <inheritdoc />
     public async ValueTask<bool> IsEnabledAsync(string feature, CancellationToken cancellationToken = new())
     {
         var targetingContext = await targetingContextAccessor.GetContextAsync();
 
         return await IsEnabledAsync<TargetingContext>(feature, targetingContext, cancellationToken);
     }
 
+    /// <inheritdoc />
     public async ValueTask<bool> IsEnabledAsync<TContext>(
         string feature,
         TContext context,
@@ -47,12 +51,14 @@ public async ValueTask<bool> IsEnabledAsync<TContext>(
         return flag is { IsEnabled: true };
     }
 
+    /// <inheritdoc />
     public async ValueTask<Variant> GetVariantAsync(string feature, CancellationToken cancellationToken = new())
     {
         var targetingContext = await targetingContextAccessor.GetContextAsync();
         return await GetVariantAsync(feature, targetingContext, cancellationToken);
     }
 
+    /// <inheritdoc />
     public async ValueTask<Variant> GetVariantAsync(
         string feature,
         ITargetingContext? context,