Add documentation remarks about order of interception
diff --git a/src/csharp/Grpc.Core/Interceptors/CallInvokerExtensions.cs b/src/csharp/Grpc.Core/Interceptors/CallInvokerExtensions.cs
index 9cec662..f1835f6 100644
--- a/src/csharp/Grpc.Core/Interceptors/CallInvokerExtensions.cs
+++ b/src/csharp/Grpc.Core/Interceptors/CallInvokerExtensions.cs
@@ -132,6 +132,13 @@
/// and returns a <see cref="Grpc.Core.Metadata" /> instance that will replace the existing
/// invocation metadata.
/// </param>
+ /// <remarks>
+ /// Multiple interceptors can be added on top of each other by calling
+ /// "invoker.Intercept(a, b, c)". The order of invocation will be "a", "b", and then "c".
+ /// Interceptors can be later added to an existing intercepted CallInvoker, effectively
+ /// building a chain like "invoker.Intercept(c).Intercept(b).Intercept(a)". Note that
+ /// in this case, the last interceptor added will be the first to take control.
+ /// </remarks>
public static CallInvoker Intercept(this CallInvoker invoker, Func<Metadata, Metadata> interceptor)
{
return new InterceptingCallInvoker(invoker, new MetadataInterceptor(interceptor));
@@ -143,6 +150,13 @@
/// </summary>
/// <param name="invoker">The underlying invoker to intercept.</param>
/// <param name="interceptor">The interceptor to intercept calls to the invoker with.</param>
+ /// <remarks>
+ /// Multiple interceptors can be added on top of each other by calling
+ /// "invoker.Intercept(a, b, c)". The order of invocation will be "a", "b", and then "c".
+ /// Interceptors can be later added to an existing intercepted CallInvoker, effectively
+ /// building a chain like "invoker.Intercept(c).Intercept(b).Intercept(a)". Note that
+ /// in this case, the last interceptor added will be the first to take control.
+ /// </remarks>
public static CallInvoker Intercept(this CallInvoker invoker, Interceptor interceptor)
{
return new InterceptingCallInvoker(invoker, interceptor);
@@ -157,6 +171,13 @@
/// An array of interceptors to intercept the calls to the invoker with.
/// Control is passed to the interceptors in the order specified.
/// </param>
+ /// <remarks>
+ /// Multiple interceptors can be added on top of each other by calling
+ /// "invoker.Intercept(a, b, c)". The order of invocation will be "a", "b", and then "c".
+ /// Interceptors can be later added to an existing intercepted CallInvoker, effectively
+ /// building a chain like "invoker.Intercept(c).Intercept(b).Intercept(a)". Note that
+ /// in this case, the last interceptor added will be the first to take control.
+ /// </remarks>
public static CallInvoker Intercept(this CallInvoker invoker, params Interceptor[] interceptors)
{
GrpcPreconditions.CheckNotNull(invoker, "invoker");
diff --git a/src/csharp/Grpc.Core/Interceptors/ChannelExtensions.cs b/src/csharp/Grpc.Core/Interceptors/ChannelExtensions.cs
index 25d1724..a095b05 100644
--- a/src/csharp/Grpc.Core/Interceptors/ChannelExtensions.cs
+++ b/src/csharp/Grpc.Core/Interceptors/ChannelExtensions.cs
@@ -32,6 +32,13 @@
/// </summary>
/// <param name="channel">The channel to intercept.</param>
/// <param name="interceptor">The interceptor to intercept the channel with.</param>
+ /// <remarks>
+ /// Multiple interceptors can be added on top of each other by calling
+ /// "channel.Intercept(a, b, c)". The order of invocation will be "a", "b", and then "c".
+ /// Interceptors can be later added to an existing intercepted channel, effectively
+ /// building a chain like "channel.Intercept(c).Intercept(b).Intercept(a)". Note that
+ /// in this case, the last interceptor added will be the first to take control.
+ /// </remarks>
public static CallInvoker Intercept(this Channel channel, Interceptor interceptor)
{
return new DefaultCallInvoker(channel).Intercept(interceptor);
@@ -46,6 +53,13 @@
/// An array of interceptors to intercept the channel with.
/// Control is passed to the interceptors in the order specified.
/// </param>
+ /// <remarks>
+ /// Multiple interceptors can be added on top of each other by calling
+ /// "channel.Intercept(a, b, c)". The order of invocation will be "a", "b", and then "c".
+ /// Interceptors can be later added to an existing intercepted channel, effectively
+ /// building a chain like "channel.Intercept(c).Intercept(b).Intercept(a)". Note that
+ /// in this case, the last interceptor added will be the first to take control.
+ /// </remarks>
public static CallInvoker Intercept(this Channel channel, params Interceptor[] interceptors)
{
return new DefaultCallInvoker(channel).Intercept(interceptors);
@@ -61,6 +75,13 @@
/// and returns a <see cref="Grpc.Core.Metadata" /> instance that will replace the existing
/// invocation metadata.
/// </param>
+ /// <remarks>
+ /// Multiple interceptors can be added on top of each other by calling
+ /// "channel.Intercept(a, b, c)". The order of invocation will be "a", "b", and then "c".
+ /// Interceptors can be later added to an existing intercepted channel, effectively
+ /// building a chain like "channel.Intercept(c).Intercept(b).Intercept(a)". Note that
+ /// in this case, the last interceptor added will be the first to take control.
+ /// </remarks>
public static CallInvoker Intercept(this Channel channel, Func<Metadata, Metadata> interceptor)
{
return new DefaultCallInvoker(channel).Intercept(interceptor);
diff --git a/src/csharp/Grpc.Core/ServerServiceDefinition.cs b/src/csharp/Grpc.Core/ServerServiceDefinition.cs
index 3e6c128..a42f543 100644
--- a/src/csharp/Grpc.Core/ServerServiceDefinition.cs
+++ b/src/csharp/Grpc.Core/ServerServiceDefinition.cs
@@ -54,6 +54,12 @@
/// This is an EXPERIMENTAL API.
/// </summary>
/// <param name="interceptor">The interceptor to register on service.</param>
+ /// <remarks>
+ /// Multiple interceptors can be added on top of each other by chaining them
+ /// like "service.Intercept(c).Intercept(b).Intercept(a)". Note that
+ /// in this case, the last interceptor added will be the first to take control,
+ /// i.e. "a" will run before "b" before "c".
+ /// </remarks>
public ServerServiceDefinition Intercept(Interceptor interceptor)
{
GrpcPreconditions.CheckNotNull(interceptor, "interceptor");