Add more documentation comments for continuation
diff --git a/src/csharp/Grpc.Core/Interceptors/Interceptor.cs b/src/csharp/Grpc.Core/Interceptors/Interceptor.cs
index c277aab..56a30c3 100644
--- a/src/csharp/Grpc.Core/Interceptors/Interceptor.cs
+++ b/src/csharp/Grpc.Core/Interceptors/Interceptor.cs
@@ -31,6 +31,12 @@
{
/// <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 @@
/// 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 @@
/// 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 @@
/// 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 @@
/// 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 @@
/// <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 @@
/// <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 @@
/// <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 @@
/// <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 @@
/// <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 @@
}
/// <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 @@
/// </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 @@
}
/// <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 @@
}
/// <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