Add more documentation comments for continuation

1 files changed, 170 insertions, 4 deletions

diff --git a/src/csharp/Grpc.Core/Interceptors/Interceptor.cs b/src/csharp/Grpc.Core/Interceptors/Interceptor.cs
index c277aab2a5..56a30c34af 100644
--- a/src/csharp/Grpc.Core/Interceptors/Interceptor.cs
+++ b/src/csharp/Grpc.Core/Interceptors/Interceptor.cs
@@ -31,6 +31,12 @@ namespace Grpc.Core.Interceptors
     {
         /// <summary>
         /// Represents a continuation for intercepting simple blocking invocations.
+        /// A delegate of this type is passed to the BlockingUnaryCall method
+        /// when an outgoing invocation is being intercepted and calling the
+        /// delegate will invoke the next interceptor in the chain, or the underlying
+        /// call invoker if called from the last interceptor. The interceptor is
+        /// allowed to call it zero, one, or multiple times, passing it the appropriate
+        /// context and request values as it sees fit.
         /// </summary>
         /// <typeparam name="TRequest">Request message type for this invocation.</typeparam>
         /// <typeparam name="TResponse">Response message type for this invocation.</typeparam>
@@ -39,12 +45,23 @@ namespace Grpc.Core.Interceptors
         /// The <see cref="Grpc.Core.Interceptors.ClientInterceptorContext{TRequest, TResponse}"/>
         /// instance to pass to the next step in the invocation process.
         /// </param>
+        /// <returns>
+        /// The response value of the invocation to return to the caller.
+        /// The interceptor can choose to return the return value of the
+        /// continuation delegate or an arbitrary value as it sees fit.
+        /// </returns>
         public delegate TResponse BlockingUnaryCallContinuation<TRequest, TResponse>(TRequest request, ClientInterceptorContext<TRequest, TResponse> context)
             where TRequest : class
             where TResponse : class;
 
         /// <summary>
         /// Represents a continuation for intercepting simple asynchronous invocations.
+        /// A delegate of this type is passed to the AsyncUnaryCall method
+        /// when an outgoing invocation is being intercepted and calling the
+        /// delegate will invoke the next interceptor in the chain, or the underlying
+        /// call invoker if called from the last interceptor. The interceptor is
+        /// allowed to call it zero, one, or multiple times, passing it the appropriate
+        /// request value and context as it sees fit.
         /// </summary>
         /// <typeparam name="TRequest">Request message type for this invocation.</typeparam>
         /// <typeparam name="TResponse">Response message type for this invocation.</typeparam>
@@ -53,12 +70,24 @@ namespace Grpc.Core.Interceptors
         /// The <see cref="Grpc.Core.Interceptors.ClientInterceptorContext{TRequest, TResponse}"/>
         /// instance to pass to the next step in the invocation process.
         /// </param>
+        /// <returns>
+        /// An instance of <see cref="Grpc.Core.AsyncUnaryCall{TResponse}" />
+        /// representing an asynchronous invocation of a unary RPC.
+        /// The interceptor can choose to return the same object returned from
+        /// the continuation delegate or an arbitrarily constructed instance as it sees fit.
+        /// </returns>
         public delegate AsyncUnaryCall<TResponse> AsyncUnaryCallContinuation<TRequest, TResponse>(TRequest request, ClientInterceptorContext<TRequest, TResponse> context)
             where TRequest : class
             where TResponse : class;
 
         /// <summary>
         /// Represents a continuation for intercepting asynchronous server-streaming invocations.
+        /// A delegate of this type is passed to the AsyncServerStreamingCall method
+        /// when an outgoing invocation is being intercepted and calling the
+        /// delegate will invoke the next interceptor in the chain, or the underlying
+        /// call invoker if called from the last interceptor. The interceptor is
+        /// allowed to call it zero, one, or multiple times, passing it the appropriate
+        /// request value and context as it sees fit.
         /// </summary>
         /// <typeparam name="TRequest">Request message type for this invocation.</typeparam>
         /// <typeparam name="TResponse">Response message type for this invocation.</typeparam>
@@ -67,12 +96,24 @@ namespace Grpc.Core.Interceptors
         /// The <see cref="Grpc.Core.Interceptors.ClientInterceptorContext{TRequest, TResponse}"/>
         /// instance to pass to the next step in the invocation process.
         /// </param>
+        /// <returns>
+        /// An instance of <see cref="Grpc.Core.AsyncServerStreamingCall{TResponse}" />
+        /// representing an asynchronous invocation of a server-streaming RPC.
+        /// The interceptor can choose to return the same object returned from
+        /// the continuation delegate or an arbitrarily constructed instance as it sees fit.
+        /// </returns>
         public delegate AsyncServerStreamingCall<TResponse> AsyncServerStreamingCallContinuation<TRequest, TResponse>(TRequest request, ClientInterceptorContext<TRequest, TResponse> context)
             where TRequest : class
             where TResponse : class;
 
         /// <summary>
         /// Represents a continuation for intercepting asynchronous client-streaming invocations.
+        /// A delegate of this type is passed to the AsyncClientStreamingCall method
+        /// when an outgoing invocation is being intercepted and calling the
+        /// delegate will invoke the next interceptor in the chain, or the underlying
+        /// call invoker if called from the last interceptor. The interceptor is
+        /// allowed to call it zero, one, or multiple times, passing it the appropriate
+        /// request value and context as it sees fit.
         /// </summary>
         /// <typeparam name="TRequest">Request message type for this invocation.</typeparam>
         /// <typeparam name="TResponse">Response message type for this invocation.</typeparam>
@@ -80,17 +121,35 @@ namespace Grpc.Core.Interceptors
         /// The <see cref="Grpc.Core.Interceptors.ClientInterceptorContext{TRequest, TResponse}"/>
         /// instance to pass to the next step in the invocation process.
         /// </param>
+        /// <returns>
+        /// An instance of <see cref="Grpc.Core.AsyncClientStreamingCall{TRequest, TResponse}" />
+        /// representing an asynchronous invocation of a client-streaming RPC.
+        /// The interceptor can choose to return the same object returned from
+        /// the continuation delegate or an arbitrarily constructed instance as it sees fit.
+        /// </returns>
         public delegate AsyncClientStreamingCall<TRequest, TResponse> AsyncClientStreamingCallContinuation<TRequest, TResponse>(ClientInterceptorContext<TRequest, TResponse> context)
             where TRequest : class
             where TResponse : class;
 
         /// <summary>
         /// Represents a continuation for intercepting asynchronous duplex invocations.
+        /// A delegate of this type is passed to the AsyncDuplexStreamingCall method
+        /// when an outgoing invocation is being intercepted and calling the
+        /// delegate will invoke the next interceptor in the chain, or the underlying
+        /// call invoker if called from the last interceptor. The interceptor is
+        /// allowed to call it zero, one, or multiple times, passing it the appropriate
+        /// request value and context as it sees fit.
         /// </summary>
         /// <param name="context">
         /// The <see cref="Grpc.Core.Interceptors.ClientInterceptorContext{TRequest, TResponse}"/>
         /// instance to pass to the next step in the invocation process.
         /// </param>
+        /// <returns>
+        /// An instance of <see cref="Grpc.Core.AsyncDuplexStreamingCall{TRequest, TResponse}" />
+        /// representing an asynchronous invocation of a duplex-streaming RPC.
+        /// The interceptor can choose to return the same object returned from
+        /// the continuation delegate or an arbitrarily constructed instance as it sees fit.
+        /// </returns>
         public delegate AsyncDuplexStreamingCall<TRequest, TResponse> AsyncDuplexStreamingCallContinuation<TRequest, TResponse>(ClientInterceptorContext<TRequest, TResponse> context)
             where TRequest : class
             where TResponse : class;
@@ -106,8 +165,15 @@ namespace Grpc.Core.Interceptors
         /// <param name="continuation">
         /// The callback that continues the invocation process.
         /// This can be invoked zero or more times by the interceptor.
+        /// The interceptor can invoke the continuation passing the given
+        /// request value and context arguments, or substitute them as it sees fit.
         /// </param>
-        /// <returns>The response message of the current invocation.</returns>
+        /// <returns>
+        /// The response message of the current invocation.
+        /// The interceptor can simply return the return value of the
+        /// continuation delegate passed to it intact, or an arbitrary
+        /// value as it sees fit.
+        /// </returns>
         public virtual TResponse BlockingUnaryCall<TRequest, TResponse>(TRequest request, ClientInterceptorContext<TRequest, TResponse> context, BlockingUnaryCallContinuation<TRequest, TResponse> continuation)
             where TRequest : class
             where TResponse : class
@@ -126,7 +192,16 @@ namespace Grpc.Core.Interceptors
         /// <param name="continuation">
         /// The callback that continues the invocation process.
         /// This can be invoked zero or more times by the interceptor.
+        /// The interceptor can invoke the continuation passing the given
+        /// request value and context arguments, or substitute them as it sees fit.
         /// </param>
+        /// <returns>
+        /// An instance of <see cref="Grpc.Core.AsyncUnaryCall{TResponse}" />
+        /// representing an asynchronous unary invocation.
+        /// The interceptor can simply return the return value of the
+        /// continuation delegate passed to it intact, or construct its
+        /// own substitute as it sees fit.
+        /// </returns>
         public virtual AsyncUnaryCall<TResponse> AsyncUnaryCall<TRequest, TResponse>(TRequest request, ClientInterceptorContext<TRequest, TResponse> context, AsyncUnaryCallContinuation<TRequest, TResponse> continuation)
             where TRequest : class
             where TResponse : class
@@ -145,7 +220,16 @@ namespace Grpc.Core.Interceptors
         /// <param name="continuation">
         /// The callback that continues the invocation process.
         /// This can be invoked zero or more times by the interceptor.
+        /// The interceptor can invoke the continuation passing the given
+        /// request value and context arguments, or substitute them as it sees fit.
         /// </param>
+        /// <returns>
+        /// An instance of <see cref="Grpc.Core.AsyncServerStreamingCall{TResponse}" />
+        /// representing an asynchronous server-streaming invocation.
+        /// The interceptor can simply return the return value of the
+        /// continuation delegate passed to it intact, or construct its
+        /// own substitute as it sees fit.
+        /// </returns>
         public virtual AsyncServerStreamingCall<TResponse> AsyncServerStreamingCall<TRequest, TResponse>(TRequest request, ClientInterceptorContext<TRequest, TResponse> context, AsyncServerStreamingCallContinuation<TRequest, TResponse> continuation)
             where TRequest : class
             where TResponse : class
@@ -163,7 +247,16 @@ namespace Grpc.Core.Interceptors
         /// <param name="continuation">
         /// The callback that continues the invocation process.
         /// This can be invoked zero or more times by the interceptor.
+        /// The interceptor can invoke the continuation passing the given
+        /// context argument, or substitute as it sees fit.
         /// </param>
+        /// <returns>
+        /// An instance of <see cref="Grpc.Core.AsyncClientStreamingCall{TRequest, TResponse}" />
+        /// representing an asynchronous client-streaming invocation.
+        /// The interceptor can simply return the return value of the
+        /// continuation delegate passed to it intact, or construct its
+        /// own substitute as it sees fit.
+        /// </returns>
         public virtual AsyncClientStreamingCall<TRequest, TResponse> AsyncClientStreamingCall<TRequest, TResponse>(ClientInterceptorContext<TRequest, TResponse> context, AsyncClientStreamingCallContinuation<TRequest, TResponse> continuation)
             where TRequest : class
             where TResponse : class
@@ -181,7 +274,16 @@ namespace Grpc.Core.Interceptors
         /// <param name="continuation">
         /// The callback that continues the invocation process.
         /// This can be invoked zero or more times by the interceptor.
+        /// The interceptor can invoke the continuation passing the given
+        /// context argument, or substitute as it sees fit.
         /// </param>
+        /// <returns>
+        /// An instance of <see cref="Grpc.Core.AsyncDuplexStreamingCall{TRequest, TResponse}" />
+        /// representing an asynchronous duplex-streaming invocation.
+        /// The interceptor can simply return the return value of the
+        /// continuation delegate passed to it intact, or construct its
+        /// own substitute as it sees fit.
+        /// </returns>
         public virtual AsyncDuplexStreamingCall<TRequest, TResponse> AsyncDuplexStreamingCall<TRequest, TResponse>(ClientInterceptorContext<TRequest, TResponse> context, AsyncDuplexStreamingCallContinuation<TRequest, TResponse> continuation)
             where TRequest : class
             where TResponse : class
@@ -190,10 +292,27 @@ namespace Grpc.Core.Interceptors
         }
 
         /// <summary>
-        /// Server-side handler for intercepting unary calls.
+        /// Server-side handler for intercepting and incoming unary call.
         /// </summary>
         /// <typeparam name="TRequest">Request message type for this method.</typeparam>
         /// <typeparam name="TResponse">Response message type for this method.</typeparam>
+        /// <param name="request">The request value of the incoming invocation.</param>
+        /// <param name="context">
+        /// An instance of <see cref="Grpc.Core.ServerCallContext" /> representing
+        /// the context of the invocation.
+        /// </param>
+        /// <param name="continuation">
+        /// A delegate that asynchronously proceeds with the invocation, calling
+        /// the next interceptor in the chain, or the service request handler,
+        /// in case of the last interceptor and return the response value of
+        /// the RPC. The interceptor can choose to call it zero or more times
+        /// at its discretion.
+        /// </param>
+        /// <returns>
+        /// A future representing the response value of the RPC. The interceptor
+        /// can simply return the return value from the continuation intact,
+        /// or an arbitrary response value as it sees fit.
+        /// </returns>
         public virtual Task<TResponse> UnaryServerHandler<TRequest, TResponse>(TRequest request, ServerCallContext context, UnaryServerMethod<TRequest, TResponse> continuation)
             where TRequest : class
             where TResponse : class
@@ -206,6 +325,25 @@ namespace Grpc.Core.Interceptors
         /// </summary>
         /// <typeparam name="TRequest">Request message type for this method.</typeparam>
         /// <typeparam name="TResponse">Response message type for this method.</typeparam>
+        /// <param name="requestStream">The request stream of the incoming invocation.</param>
+        /// <param name="context">
+        /// An instance of <see cref="Grpc.Core.ServerCallContext" /> representing
+        /// the context of the invocation.
+        /// </param>
+        /// <param name="continuation">
+        /// A delegate that asynchronously proceeds with the invocation, calling
+        /// the next interceptor in the chain, or the service request handler,
+        /// in case of the last interceptor and return the response value of
+        /// the RPC. The interceptor can choose to call it zero or more times
+        /// at its discretion.
+        /// </param>
+        /// <returns>
+        /// A future representing the response value of the RPC. The interceptor
+        /// can simply return the return value from the continuation intact,
+        /// or an arbitrary response value as it sees fit. The interceptor has
+        /// the ability to wrap or substitute the request stream when calling
+        /// the continuation.
+        /// </returns>
         public virtual Task<TResponse> ClientStreamingServerHandler<TRequest, TResponse>(IAsyncStreamReader<TRequest> requestStream, ServerCallContext context, ClientStreamingServerMethod<TRequest, TResponse> continuation)
             where TRequest : class
             where TResponse : class
@@ -214,10 +352,24 @@ namespace Grpc.Core.Interceptors
         }
 
         /// <summary>
-        /// Server-side handler for intercepting server streaming calls.
+        /// Server-side handler for intercepting server streaming call.
         /// </summary>
         /// <typeparam name="TRequest">Request message type for this method.</typeparam>
         /// <typeparam name="TResponse">Response message type for this method.</typeparam>
+        /// <param name="request">The request value of the incoming invocation.</param>
+        /// <param name="responseStream">The response stream of the incoming invocation.</param>
+        /// <param name="context">
+        /// An instance of <see cref="Grpc.Core.ServerCallContext" /> representing
+        /// the context of the invocation.
+        /// </param>
+        /// <param name="continuation">
+        /// A delegate that asynchronously proceeds with the invocation, calling
+        /// the next interceptor in the chain, or the service request handler,
+        /// in case of the last interceptor and the interceptor can choose to
+        /// call it zero or more times at its discretion. The interceptor has
+        /// the ability to wrap or substitute the request value and the response stream
+        /// when calling the continuation.
+        /// </param>
         public virtual Task ServerStreamingServerHandler<TRequest, TResponse>(TRequest request, IServerStreamWriter<TResponse> responseStream, ServerCallContext context, ServerStreamingServerMethod<TRequest, TResponse> continuation)
             where TRequest : class
             where TResponse : class
@@ -226,10 +378,24 @@ namespace Grpc.Core.Interceptors
         }
 
         /// <summary>
-        /// Server-side handler for intercepting bidi streaming calls.
+        /// Server-side handler for intercepting bidirectional streaming calls.
         /// </summary>
         /// <typeparam name="TRequest">Request message type for this method.</typeparam>
         /// <typeparam name="TResponse">Response message type for this method.</typeparam>
+        /// <param name="requestStream">The request stream of the incoming invocation.</param>
+        /// <param name="responseStream">The response stream of the incoming invocation.</param>
+        /// <param name="context">
+        /// An instance of <see cref="Grpc.Core.ServerCallContext" /> representing
+        /// the context of the invocation.
+        /// </param>
+        /// <param name="continuation">
+        /// A delegate that asynchronously proceeds with the invocation, calling
+        /// the next interceptor in the chain, or the service request handler,
+        /// in case of the last interceptor and the interceptor can choose to
+        /// call it zero or more times at its discretion. The interceptor has
+        /// the ability to wrap or substitute the request and response streams
+        /// when calling the continuation.
+        /// </param>
         public virtual Task DuplexStreamingServerHandler<TRequest, TResponse>(IAsyncStreamReader<TRequest> requestStream, IServerStreamWriter<TResponse> responseStream, ServerCallContext context, DuplexStreamingServerMethod<TRequest, TResponse> continuation)
             where TRequest : class
             where TResponse : class