improving doc comments (#5550)

adding some missing doc comments

docs/dotnet/core/installation.md

@@ -20,3 +20,29 @@ Or, add via `<PackageReference>`
 <PackageReference Include="Microsoft.AutoGen.Contracts" Version="0.4.0-dev.1" />
 <PackageReference Include="Microsoft.AutoGen.Core" Version="0.4.0-dev.1" />
 ```
+
+# Additional Packages
+
+The *Core* and *Contracts* packages will give you what you need for writing and running agents using the Core API within a single process. 
+
+- *Microsoft.AutoGen.AgentChat* - An implementation of the AgentChat package for building chat-centric agent orchestration on top of the Core SDK
+- *Microsoft.AutoGen.Agents* - a package that has a small number of default agents you can use. 
+- *Microsoft.AutoGen.Extensions* - Extensions to support closely related projects including Aspire, Microsoft.Extensions.AI, and Semantic Kernel
+
+```sh
+dotnet add package Microsoft.AutoGen.AgentChat --version 0.4.0-dev-1
+dotnet add package Microsoft.AutoGen.Agents --version 0.4.0-dev-1
+dotnet add package Microsoft.AutoGen.Extensions --version 0.4.0-dev-1
+```
+
+To enable running a system with agents in different processes that allows for x-language communication between python and .NET agents, there are additional packages:
+
+- *Microsoft.AutoGen.Core.Grpc* - the .NET client runtime for agents in a distributed system. It has the same API as *Microsoft.AutoGen.Core*. 
+- *Microsoft.AutoGen.RuntimeGatewway.Grpc* - the .NET server side of the distributed system that allows you to run multiple gateways to manage fleets of agents and enables x-language interoperability. 
+- *Microsoft.AutoGen.AgentHost* - A .NET Aspire project that hosts the Grpc Service
+
+```sh
+dotnet add package Microsoft.AutoGen.Core.Grpc --version 0.4.0-dev-1
+dotnet add package Microsoft.AutoGen.RuntimeGateway.Grpc --version 0.4.0-dev-1
+dotnet add package Microsoft.AutoGen.AgentHost --version 0.4.0-dev-1
+```

dotnet/src/Microsoft.AutoGen/RuntimeGateway.Grpc/Abstractions/IConnection.cs

@@ -1,7 +0,0 @@
-// Copyright (c) Microsoft Corporation. All rights reserved.
-// IConnection.cs
-
-namespace Microsoft.AutoGen.RuntimeGateway.Grpc.Abstractions;
-public interface IConnection
-{
-}

dotnet/src/Microsoft.AutoGen/RuntimeGateway.Grpc/Abstractions/IGateway.cs

@@ -5,11 +5,45 @@ using Microsoft.AutoGen.Protobuf;
 
 namespace Microsoft.AutoGen.RuntimeGateway.Grpc.Abstractions;
 
+/// <summary>
+/// Defines the gateway interface for handling RPC requests and subscriptions.
+/// Note that all of the request types are generated from the proto file.
+/// </summary>
 public interface IGateway : IGrainObserver
 {
+    /// <summary>
+    /// Invokes a request asynchronously.
+    /// </summary>
+    /// <param name="request">The RPC request.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains the RPC response.</returns>
     ValueTask<RpcResponse> InvokeRequestAsync(RpcRequest request);
+
+    /// <summary>
+    /// Registers an agent type asynchronously.
+    /// </summary>
+    /// <param name="request">The register agent type request.</param>
+    /// <param name="context">The server call context.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains the register agent type response.</returns>
     ValueTask<RegisterAgentTypeResponse> RegisterAgentTypeAsync(RegisterAgentTypeRequest request, ServerCallContext context);
+
+    /// <summary>
+    /// Subscribes to a topic asynchronously.
+    /// </summary>
+    /// <param name="request">The add subscription request.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains the add subscription response.</returns>
     ValueTask<AddSubscriptionResponse> SubscribeAsync(AddSubscriptionRequest request);
+
+    /// <summary>
+    /// Unsubscribes from a topic asynchronously.
+    /// </summary>
+    /// <param name="request">The remove subscription request.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains the remove subscription response.</returns>
     ValueTask<RemoveSubscriptionResponse> UnsubscribeAsync(RemoveSubscriptionRequest request);
+
+    /// <summary>
+    /// Gets the subscriptions asynchronously.
+    /// </summary>
+    /// <param name="request">The get subscriptions request.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains the list of subscriptions.</returns>
     ValueTask<List<Subscription>> GetSubscriptionsAsync(GetSubscriptionsRequest request);
 }

dotnet/src/Microsoft.AutoGen/RuntimeGateway.Grpc/Abstractions/IGatewayRegistry.cs

@@ -5,7 +5,7 @@ using Microsoft.AutoGen.Protobuf;
 namespace Microsoft.AutoGen.RuntimeGateway.Grpc.Abstractions;
 
 /// <summary>
-/// Interface for managing agent registration, placement, and subscriptions.
+/// Keeps track of which agents are registered with which gateways.
 /// </summary>
 public interface IGatewayRegistry : IRegistry
 {
@@ -27,6 +27,7 @@ public interface IGatewayRegistry : IRegistry
     /// Registers a new agent type with the specified worker.
     /// </summary>
     /// <param name="request">The request containing agent type details.</param>
+    /// <param name="clientId">The client ID of the worker.</param>
     /// <param name="worker">The worker to register the agent type with.</param>
     /// <returns>A task representing the asynchronous operation.</returns>
     ValueTask RegisterAgentTypeAsync(RegisterAgentTypeRequest request, string clientId, IGateway worker);

dotnet/src/Microsoft.AutoGen/RuntimeGateway.Grpc/Abstractions/IRegistry.cs

@@ -5,7 +5,6 @@ namespace Microsoft.AutoGen.RuntimeGateway.Grpc.Abstractions;
 
 public interface IRegistry
 {
-
     /// <summary>
     /// Gets a list of agents subscribed to and handling the specified topic and event type.
     /// </summary>
@@ -28,11 +27,12 @@ public interface IRegistry
     /// <param name="request">The unsubscription request.</param>
     /// <returns>A task representing the asynchronous operation.</returns>
     /// <remarks>removing CancellationToken from here as it is not compatible with Orleans Serialization</remarks>
-    ValueTask UnsubscribeAsync(RemoveSubscriptionRequest request); // TODO: This should have its own request type.
+    ValueTask UnsubscribeAsync(RemoveSubscriptionRequest request);  // TODO: This should have its own request type.
 
     /// <summary>
     /// Gets the subscriptions for a specified agent type.
     /// </summary>
+    /// <param name="request">The get subscriptions request.</param>
     /// <returns>A task representing the asynchronous operation, with the subscriptions as the result.</returns>
     ValueTask<List<Subscription>> GetSubscriptionsAsync(GetSubscriptionsRequest request);
 }

dotnet/src/Microsoft.AutoGen/RuntimeGateway.Grpc/Services/Grpc/GrpcWorkerConnection.cs

@@ -3,11 +3,10 @@
 using System.Threading.Channels;
 using Grpc.Core;
 using Microsoft.AutoGen.Protobuf;
-using Microsoft.AutoGen.RuntimeGateway.Grpc.Abstractions;
 
 namespace Microsoft.AutoGen.RuntimeGateway.Grpc;
 
-public sealed class GrpcWorkerConnection : IAsyncDisposable, IConnection
+public sealed class GrpcWorkerConnection : IAsyncDisposable
 {
     private static long s_nextConnectionId;
     private Task _readTask = Task.CompletedTask;
@@ -57,6 +56,7 @@ public sealed class GrpcWorkerConnection : IAsyncDisposable, IConnection
 
     private readonly Channel<Message> _outboundMessages;
 
+    /// <inheritdoc/>
     public void AddSupportedType(string type)
     {
         lock (_lock)
@@ -65,6 +65,7 @@ public sealed class GrpcWorkerConnection : IAsyncDisposable, IConnection
         }
     }
 
+    /// <inheritdoc/>
     public HashSet<string> GetSupportedTypes()
     {
         lock (_lock)
@@ -73,10 +74,13 @@ public sealed class GrpcWorkerConnection : IAsyncDisposable, IConnection
         }
     }
 
+    /// <inheritdoc/>
     public async Task SendMessage(Message message)
     {
         await _outboundMessages.Writer.WriteAsync(message).ConfigureAwait(false);
     }
+
+    /// <inheritdoc/>
     public async Task RunReadPump()
     {
         await Task.CompletedTask.ConfigureAwait(ConfigureAwaitOptions.ForceYielding);
@@ -98,6 +102,7 @@ public sealed class GrpcWorkerConnection : IAsyncDisposable, IConnection
         }
     }
 
+    /// <inheritdoc/>
     public async Task RunWritePump()
     {
         await Task.CompletedTask.ConfigureAwait(ConfigureAwaitOptions.ForceYielding);
@@ -117,11 +122,13 @@ public sealed class GrpcWorkerConnection : IAsyncDisposable, IConnection
         }
     }
 
+    /// <inheritdoc/>
     public async ValueTask DisposeAsync()
     {
         _shutdownCancellationToken.Cancel();
         await Completion.ConfigureAwait(ConfigureAwaitOptions.SuppressThrowing);
     }
 
+    /// <inheritdoc/>
     public override string ToString() => $"Connection-{_connectionId}";
 }

dotnet/src/Microsoft.AutoGen/RuntimeGateway.Grpc/Services/Orleans/RegistryGrain.cs

@@ -277,6 +277,7 @@ internal sealed class RegistryGrain([PersistentState("state", "AgentRegistryStor
         }
         return new(subscriptions);
     }
+
     private sealed class WorkerState
     {
         public HashSet<string> SupportedTypes { get; set; } = [];

dotnet/src/Microsoft.AutoGen/RuntimeGateway.Grpc/Services/Orleans/Surrogates/TypeSubscriptionSurrogate.cs

@@ -17,6 +17,11 @@ public struct TypeSubscriptionSurrogate
 public sealed class TypeSubscriptionSurrogateConverter :
     IConverter<TypeSubscription, TypeSubscriptionSurrogate>
 {
+    /// <summary>
+    /// Converts from the surrogate to the original type.
+    /// </summary>
+    /// <param name="surrogate">The surrogate to convert from.</param>
+    /// <returns>The original type.</returns>
     public TypeSubscription ConvertFromSurrogate(
         in TypeSubscriptionSurrogate surrogate) =>
         new TypeSubscription
@@ -25,6 +30,11 @@ public sealed class TypeSubscriptionSurrogateConverter :
             AgentType = surrogate.AgentType
         };
 
+    /// <summary>
+    /// Converts from the original type to the surrogate.
+    /// </summary>
+    /// <param name="value">The original type to convert from.</param>
+    /// <returns>The surrogate type.</returns>
     public TypeSubscriptionSurrogate ConvertToSurrogate(
         in TypeSubscription value) =>
         new TypeSubscriptionSurrogate