Document LeanPipe publisher public API in code

publisher/src/LeanCode.Pipe/BasicTopicKeys.cs

@@ -2,9 +2,17 @@
 
 namespace LeanCode.Pipe;
 
+/// <summary>
+/// Convenience class for implementing topic keys for simple topics.
+/// </summary>
+/// <typeparam name="TT">Topic</typeparam>
 public abstract class BasicTopicKeys<TT> : ISubscribingKeys<TT>
     where TT : ITopic
 {
+    /// <summary>
+    /// Used to generate SignalR groups keys when client subscribes, unsubscribes
+    /// or when the message is published.
+    /// </summary>
     public abstract IEnumerable<string> Get(TT topic);
 
     public ValueTask<IEnumerable<string>> GetForSubscribingAsync(
@@ -13,10 +21,12 @@ LeanPipeContext context
     ) => ValueTask.FromResult(Get(topic));
 }
 
+/// <inheritdoc cref="BasicTopicKeys{TT}"/>
 public abstract class BasicTopicKeys<TT, TN1> : IPublishingKeys<TT, TN1>
     where TT : ITopic, IProduceNotification<TN1>
     where TN1 : notnull
 {
+    /// <inheritdoc cref="BasicTopicKeys{TT}.Get"/>
     public abstract IEnumerable<string> Get(TT topic);
 
     public ValueTask<IEnumerable<string>> GetForSubscribingAsync(
@@ -31,6 +41,7 @@ CancellationToken ct
     ) => ValueTask.FromResult(Get(topic));
 }
 
+/// <inheritdoc cref="BasicTopicKeys{TT}"/>
 public abstract class BasicTopicKeys<TT, TN1, TN2>
     : BasicTopicKeys<TT, TN1>,
         IPublishingKeys<TT, TN2>
@@ -45,6 +56,7 @@ public ValueTask<IEnumerable<string>> GetForPublishingAsync(
     ) => ValueTask.FromResult(Get(topic));
 }
 
+/// <inheritdoc cref="BasicTopicKeys{TT}"/>
 public abstract class BasicTopicKeys<TT, TN1, TN2, TN3>
     : BasicTopicKeys<TT, TN1, TN2>,
         IPublishingKeys<TT, TN3>
@@ -63,6 +75,7 @@ public ValueTask<IEnumerable<string>> GetForPublishingAsync(
     ) => ValueTask.FromResult(Get(topic));
 }
 
+/// <inheritdoc cref="BasicTopicKeys{TT}"/>
 public abstract class BasicTopicKeys<TT, TN1, TN2, TN3, TN4>
     : BasicTopicKeys<TT, TN1, TN2, TN3>,
         IPublishingKeys<TT, TN4>
@@ -83,6 +96,7 @@ public ValueTask<IEnumerable<string>> GetForPublishingAsync(
     ) => ValueTask.FromResult(Get(topic));
 }
 
+/// <inheritdoc cref="BasicTopicKeys{TT}"/>
 public abstract class BasicTopicKeys<TT, TN1, TN2, TN3, TN4, TN5>
     : BasicTopicKeys<TT, TN1, TN2, TN3, TN4>,
         IPublishingKeys<TT, TN5>
@@ -105,6 +119,7 @@ public ValueTask<IEnumerable<string>> GetForPublishingAsync(
     ) => ValueTask.FromResult(Get(topic));
 }
 
+/// <inheritdoc cref="BasicTopicKeys{TT}"/>
 public abstract class BasicTopicKeys<TT, TN1, TN2, TN3, TN4, TN5, TN6>
     : BasicTopicKeys<TT, TN1, TN2, TN3, TN4, TN5>,
         IPublishingKeys<TT, TN6>
@@ -129,6 +144,7 @@ public ValueTask<IEnumerable<string>> GetForPublishingAsync(
     ) => ValueTask.FromResult(Get(topic));
 }
 
+/// <inheritdoc cref="BasicTopicKeys{TT}"/>
 public abstract class BasicTopicKeys<TT, TN1, TN2, TN3, TN4, TN5, TN6, TN7>
     : BasicTopicKeys<TT, TN1, TN2, TN3, TN4, TN5, TN6>,
         IPublishingKeys<TT, TN7>

publisher/src/LeanCode.Pipe/ITopicKeys.cs

@@ -2,16 +2,26 @@
 
 namespace LeanCode.Pipe;
 
+/// <remarks>
+/// Should be implemented in a single class per topic with <see cref="IPublishingKeys{TTopic,TNotification}"/>
+/// for all topics notifications.
+/// </remarks>
 public interface ISubscribingKeys<in TTopic>
     where TTopic : ITopic
 {
+    /// <summary>
+    /// Used to generate SignalR groups keys when client subscribes or unsubscribes.
+    /// </summary>
     ValueTask<IEnumerable<string>> GetForSubscribingAsync(TTopic topic, LeanPipeContext context);
 }
 
 public interface IPublishingKeys<in TTopic, TNotification> : ISubscribingKeys<TTopic>
     where TTopic : ITopic, IProduceNotification<TNotification>
     where TNotification : notnull
 {
+    /// <summary>
+    /// Used to generate SignalR groups keys to which send message to.
+    /// </summary>
     ValueTask<IEnumerable<string>> GetForPublishingAsync(
         TTopic topic,
         TNotification notification,

publisher/src/LeanCode.Pipe/LeanPipeContext.cs

@@ -2,6 +2,9 @@
 
 namespace LeanCode.Pipe;
 
+/// <summary>
+/// Context that is included in all LeanPipe subscriptions.
+/// </summary>
 public class LeanPipeContext
 {
     public LeanPipeContext(HttpContext httpContext)

publisher/src/LeanCode.Pipe/LeanPipeEndpointRouteBuilderExtensions.cs

@@ -1,3 +1,4 @@
+using System.Diagnostics.CodeAnalysis;
 using Microsoft.AspNetCore.Builder;
 using Microsoft.AspNetCore.Http.Connections;
 using Microsoft.AspNetCore.Routing;
@@ -6,17 +7,23 @@ namespace LeanCode.Pipe;
 
 public static class LeanPipeEndpointRouteBuilderExtensions
 {
+    /// <summary>
+    /// Maps LeanPipe SignalR hub on the specified endpoint.
+    /// </summary>
     public static IHubEndpointConventionBuilder MapLeanPipe(
         this IEndpointRouteBuilder endpoints,
-        string pattern
+        [StringSyntax("Route")] string pattern
     )
     {
         return endpoints.MapHub<LeanPipeSubscriber>(pattern);
     }
 
+    /// <summary>
+    /// Maps LeanPipe SignalR hub on the specified endpoint.
+    /// </summary>
     public static IHubEndpointConventionBuilder MapLeanPipe(
         this IEndpointRouteBuilder endpoints,
-        string pattern,
+        [StringSyntax("Route")] string pattern,
         Action<HttpConnectionDispatcherOptions>? configureOptions
     )
     {

publisher/src/LeanCode.Pipe/LeanPipePublisher.cs

@@ -4,6 +4,10 @@
 
 namespace LeanCode.Pipe;
 
+/// <summary>
+/// Allows publishing notifications to instances of <see cref="TTopic"/>.
+/// Conveniently used with extension methods from <see cref="LeanPipePublisherExtensions"/>.
+/// </summary>
 public class LeanPipePublisher<TTopic>
     where TTopic : ITopic
 {
@@ -31,6 +35,10 @@ internal async Task PublishAsync(
 
 public static class LeanPipePublisherExtensions
 {
+    /// <summary>
+    /// Publishes to topic instance using provided SignalR groups keys.
+    /// Omits publishing keys implemented in <see cref="IPublishingKeys{TTopic,TNotification}"/>.
+    /// </summary>
     public static async Task PublishAsync<TTopic, TNotification>(
         this LeanPipePublisher<TTopic> publisher,
         IEnumerable<string> keys,
@@ -46,6 +54,10 @@ public static async Task PublishAsync<TTopic, TNotification>(
         await publisher.PublishAsync(keys, payload, ct);
     }
 
+    /// <summary>
+    /// Publishes to topic instance using SignalR groups keys generated via implementation of
+    /// <see cref="IPublishingKeys{TTopic,TNotification}"/>.
+    /// </summary>
     public static async Task PublishAsync<TTopic, TNotification>(
         this LeanPipePublisher<TTopic> publisher,
         TTopic topic,

publisher/src/LeanCode.Pipe/LeanPipeServiceCollectionExtensions.cs

@@ -8,6 +8,11 @@ namespace LeanCode.Pipe;
 
 public static class LeanPipeServiceCollectionExtensions
 {
+    /// <summary>
+    /// Adds all classes required for LeanPipe to function to DI.
+    /// </summary>
+    /// <returns>Service builder allowing for overriding default LeanPipe implementations
+    /// and further configuration.</returns>
     public static LeanPipeServicesBuilder AddLeanPipe(
         this IServiceCollection services,
         TypesCatalog topics,
@@ -28,6 +33,10 @@ TypesCatalog handlers
     }
 }
 
+/// <summary>
+/// Allows for overriding default LeanPipe implementations
+/// and further configuration.
+/// </summary>
 public class LeanPipeServicesBuilder
 {
     public IServiceCollection Services { get; }
@@ -43,26 +52,38 @@ public LeanPipeServicesBuilder(IServiceCollection services, TypesCatalog topics)
         Services.AddSingleton<IEnvelopeDeserializer>(new DefaultEnvelopeDeserializer(topics, null));
     }
 
+    /// <summary>
+    /// Overrides serializing options used in subscription envelope deserializer.
+    /// </summary>
     public LeanPipeServicesBuilder WithEnvelopeDeserializerOptions(JsonSerializerOptions options)
     {
         this.options = options;
         ReplaceDefaultEnvelopeDeserializer();
         return this;
     }
 
+    /// <summary>
+    /// Overrides subscription envelope deserializer.
+    /// </summary>
     public LeanPipeServicesBuilder WithEnvelopeDeserializer(IEnvelopeDeserializer deserializer)
     {
         Services.Replace(new ServiceDescriptor(typeof(IEnvelopeDeserializer), deserializer));
         return this;
     }
 
+    /// <summary>
+    /// Adds topics from another <see cref="TypesCatalog"/>.
+    /// </summary>
     public LeanPipeServicesBuilder AddTopics(TypesCatalog newTopics)
     {
         topics = topics.Merge(newTopics);
         ReplaceDefaultEnvelopeDeserializer();
         return this;
     }
 
+    /// <summary>
+    /// Adds subscription handlers and keys generators from another <see cref="TypesCatalog"/>.
+    /// </summary>
     public LeanPipeServicesBuilder AddHandlers(TypesCatalog newHandlers)
     {
         Services.RegisterGenericTypes(

publisher/src/LeanCode.Pipe/SubscriptionHandler.cs

@@ -12,7 +12,7 @@ ValueTask<bool> OnSubscribedAsync(
         LeanPipeContext context
     );
 
-    /// <returns>Whether subscription was correctly established.</returns>
+    /// <returns>Whether subscription was correctly severed.</returns>
     ValueTask<bool> OnUnsubscribedAsync(
         TTopic topic,
         LeanPipeSubscriber leanPipeSubscriber,

publisher/src/LeanCode.Pipe/SubscriptionHandlerWrapper.cs

@@ -9,6 +9,7 @@ ValueTask<bool> OnSubscribedAsync(
         LeanPipeSubscriber leanPipeSubscriber,
         LeanPipeContext context
     );
+
     ValueTask<bool> OnUnsubscribedAsync(
         object topic,
         LeanPipeSubscriber leanPipeSubscriber,