AI seeded comments from robch and then edited by stephentoub (#238)

* AI generated `///` comment updates

* Fix compilation issues

* Fix incorrect XML comment structure

* Update all Client comments

* Update all Configuration comments

* Update all Messages comments

* Update all Transport comments

* Update all Types comments

* Update all Server comments

* Undo some commenting

---------

Co-authored-by: Stephen Toub <stoub@microsoft.com>

src/ModelContextProtocol/IMcpEndpoint.cs

@@ -1,19 +1,68 @@
-using ModelContextProtocol.Protocol.Messages;
+using ModelContextProtocol.Client;
+using ModelContextProtocol.Protocol.Messages;
+using ModelContextProtocol.Server;
 
 namespace ModelContextProtocol;
 
-/// <summary>Represents a client or server MCP endpoint.</summary>
+/// <summary>
+/// Represents a client or server Model Context Protocol (MCP) endpoint.
+/// </summary>
+/// <remarks>
+/// <para>
+/// The MCP endpoint provides the core communication functionality used by both clients and servers:
+/// <list type="bullet">
+///   <item>Sending JSON-RPC requests and receiving responses.</item>
+///   <item>Sending notifications to the connected endpoint.</item>
+///   <item>Registering handlers for receiving notifications.</item>
+/// </list>
+/// </para>
+/// <para>
+/// <see cref="IMcpEndpoint"/> serves as the base interface for both <see cref="IMcpClient"/> and 
+/// <see cref="IMcpServer"/> interfaces, providing the common functionality needed for MCP protocol 
+/// communication. Most applications will use these more specific interfaces rather than working with 
+/// <see cref="IMcpEndpoint"/> directly.
+/// </para>
+/// <para>
+/// All MCP endpoints should be properly disposed after use as they implement <see cref="IAsyncDisposable"/>.
+/// </para>
+/// </remarks>
 public interface IMcpEndpoint : IAsyncDisposable
 {
-    /// <summary>Sends a JSON-RPC request to the connected endpoint.</summary>
+    /// <summary>
+    /// Sends a JSON-RPC request to the connected endpoint and waits for a response.
+    /// </summary>
     /// <param name="request">The JSON-RPC request to send.</param>
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
-    /// <returns>A task containing the client's response.</returns>
+    /// <returns>A task containing the endpoint's response.</returns>
+    /// <exception cref="McpException">The transport is not connected, or another error occurs during request processing.</exception>
+    /// <remarks>
+    /// This method provides low-level access to send raw JSON-RPC requests. For most use cases,
+    /// consider using the strongly-typed extension methods that provide a more convenient API.
+    /// </remarks>
     Task<JsonRpcResponse> SendRequestAsync(JsonRpcRequest request, CancellationToken cancellationToken = default);
 
-    /// <summary>Sends a message to the connected endpoint.</summary>
-    /// <param name="message">The message.</param>
+    /// <summary>
+    /// Sends a JSON-RPC message to the connected endpoint.
+    /// </summary>
+    /// <param name="message">
+    /// The JSON-RPC message to send. This can be any type that implements IJsonRpcMessage, such as 
+    /// JsonRpcRequest, JsonRpcResponse, JsonRpcNotification, or JsonRpcError.
+    /// </param>
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A task that represents the asynchronous send operation.</returns>
+    /// <exception cref="McpException">The transport is not connected.</exception>
+    /// <exception cref="ArgumentNullException"><paramref name="message"/> is <see langword="null"/>.</exception>
+    /// <remarks>
+    /// <para>
+    /// This method provides low-level access to send any JSON-RPC message. For specific message types,
+    /// consider using the higher-level methods such as <see cref="SendRequestAsync"/> or extension methods
+    /// like <see cref="McpEndpointExtensions.SendNotificationAsync(IMcpEndpoint, string, CancellationToken)"/>,
+    /// which provide a simpler API.
+    /// </para>
+    /// <para>
+    /// The method will serialize the message and transmit it using the underlying transport mechanism.
+    /// </para>
+    /// </remarks>
     Task SendMessageAsync(IJsonRpcMessage message, CancellationToken cancellationToken = default);
 
     /// <summary>Registers a handler to be invoked when a notification for the specified method is received.</summary>