Merge github.com:grpc/grpc into naming-crisis

32 files changed, 200 insertions, 38 deletions

diff --git a/src/csharp/Grpc.Auth/AuthInterceptors.cs b/src/csharp/Grpc.Auth/AuthInterceptors.cs
index 61338f7f0e..c8ab4d9af6 100644
--- a/src/csharp/Grpc.Auth/AuthInterceptors.cs
+++ b/src/csharp/Grpc.Auth/AuthInterceptors.cs
@@ -41,7 +41,8 @@ using Grpc.Core.Utils;
 namespace Grpc.Auth
 {
     /// <summary>
-    /// Factory methods to create authorization interceptors.
+    /// Factory methods to create authorization interceptors. Interceptors created can be registered with gRPC client classes (autogenerated client stubs that
+    /// inherit from <see cref="Grpc.Core.ClientBase"/>).
     /// </summary>
     public static class AuthInterceptors
     {
@@ -52,6 +53,8 @@ namespace Grpc.Auth
         /// Creates interceptor that will obtain access token from any credential type that implements
         /// <c>ITokenAccess</c>. (e.g. <c>GoogleCredential</c>).
         /// </summary>
+        /// <param name="credential">The credential to use to obtain access tokens.</param>
+        /// <returns>The header interceptor.</returns>
         public static HeaderInterceptor FromCredential(ITokenAccess credential)
         {
             return new HeaderInterceptor((method, authUri, metadata) =>
@@ -67,6 +70,7 @@ namespace Grpc.Auth
         /// Creates OAuth2 interceptor that will use given access token as authorization.
         /// </summary>
         /// <param name="accessToken">OAuth2 access token.</param>
+        /// <returns>The header interceptor.</returns>
         public static HeaderInterceptor FromAccessToken(string accessToken)
         {
             Preconditions.CheckNotNull(accessToken);
diff --git a/src/csharp/Grpc.Core/AsyncClientStreamingCall.cs b/src/csharp/Grpc.Core/AsyncClientStreamingCall.cs
index dbaa3085c5..5646fed3d9 100644
--- a/src/csharp/Grpc.Core/AsyncClientStreamingCall.cs
+++ b/src/csharp/Grpc.Core/AsyncClientStreamingCall.cs
@@ -40,6 +40,8 @@ namespace Grpc.Core
     /// <summary>
     /// Return type for client streaming calls.
     /// </summary>
+    /// <typeparam name="TRequest">Request message type for this call.</typeparam>
+    /// <typeparam name="TResponse">Response message type for this call.</typeparam>
     public sealed class AsyncClientStreamingCall<TRequest, TResponse> : IDisposable
     {
         readonly IClientStreamWriter<TRequest> requestStream;
@@ -49,7 +51,7 @@ namespace Grpc.Core
         readonly Func<Metadata> getTrailersFunc;
         readonly Action disposeAction;
 
-        public AsyncClientStreamingCall(IClientStreamWriter<TRequest> requestStream, Task<TResponse> responseAsync, Task<Metadata> responseHeadersAsync, Func<Status> getStatusFunc, Func<Metadata> getTrailersFunc, Action disposeAction)
+        internal AsyncClientStreamingCall(IClientStreamWriter<TRequest> requestStream, Task<TResponse> responseAsync, Task<Metadata> responseHeadersAsync, Func<Status> getStatusFunc, Func<Metadata> getTrailersFunc, Action disposeAction)
         {
             this.requestStream = requestStream;
             this.responseAsync = responseAsync;
diff --git a/src/csharp/Grpc.Core/AsyncDuplexStreamingCall.cs b/src/csharp/Grpc.Core/AsyncDuplexStreamingCall.cs
index ee7ba29695..e75108c7e5 100644
--- a/src/csharp/Grpc.Core/AsyncDuplexStreamingCall.cs
+++ b/src/csharp/Grpc.Core/AsyncDuplexStreamingCall.cs
@@ -39,6 +39,8 @@ namespace Grpc.Core
     /// <summary>
     /// Return type for bidirectional streaming calls.
     /// </summary>
+    /// <typeparam name="TRequest">Request message type for this call.</typeparam>
+    /// <typeparam name="TResponse">Response message type for this call.</typeparam>
     public sealed class AsyncDuplexStreamingCall<TRequest, TResponse> : IDisposable
     {
         readonly IClientStreamWriter<TRequest> requestStream;
@@ -48,7 +50,7 @@ namespace Grpc.Core
         readonly Func<Metadata> getTrailersFunc;
         readonly Action disposeAction;
 
-        public AsyncDuplexStreamingCall(IClientStreamWriter<TRequest> requestStream, IAsyncStreamReader<TResponse> responseStream, Task<Metadata> responseHeadersAsync, Func<Status> getStatusFunc, Func<Metadata> getTrailersFunc, Action disposeAction)
+        internal AsyncDuplexStreamingCall(IClientStreamWriter<TRequest> requestStream, IAsyncStreamReader<TResponse> responseStream, Task<Metadata> responseHeadersAsync, Func<Status> getStatusFunc, Func<Metadata> getTrailersFunc, Action disposeAction)
         {
             this.requestStream = requestStream;
             this.responseStream = responseStream;
diff --git a/src/csharp/Grpc.Core/AsyncServerStreamingCall.cs b/src/csharp/Grpc.Core/AsyncServerStreamingCall.cs
index 2853a79ce6..f953091984 100644
--- a/src/csharp/Grpc.Core/AsyncServerStreamingCall.cs
+++ b/src/csharp/Grpc.Core/AsyncServerStreamingCall.cs
@@ -39,6 +39,7 @@ namespace Grpc.Core
     /// <summary>
     /// Return type for server streaming calls.
     /// </summary>
+    /// <typeparam name="TResponse">Response message type for this call.</typeparam>
     public sealed class AsyncServerStreamingCall<TResponse> : IDisposable
     {
         readonly IAsyncStreamReader<TResponse> responseStream;
@@ -47,7 +48,7 @@ namespace Grpc.Core
         readonly Func<Metadata> getTrailersFunc;
         readonly Action disposeAction;
 
-        public AsyncServerStreamingCall(IAsyncStreamReader<TResponse> responseStream, Task<Metadata> responseHeadersAsync, Func<Status> getStatusFunc, Func<Metadata> getTrailersFunc, Action disposeAction)
+        internal AsyncServerStreamingCall(IAsyncStreamReader<TResponse> responseStream, Task<Metadata> responseHeadersAsync, Func<Status> getStatusFunc, Func<Metadata> getTrailersFunc, Action disposeAction)
         {
             this.responseStream = responseStream;
             this.responseHeadersAsync = responseHeadersAsync;
diff --git a/src/csharp/Grpc.Core/AsyncUnaryCall.cs b/src/csharp/Grpc.Core/AsyncUnaryCall.cs
index 154a17a33e..97df8f5e91 100644
--- a/src/csharp/Grpc.Core/AsyncUnaryCall.cs
+++ b/src/csharp/Grpc.Core/AsyncUnaryCall.cs
@@ -40,6 +40,7 @@ namespace Grpc.Core
     /// <summary>
     /// Return type for single request - single response call.
     /// </summary>
+    /// <typeparam name="TResponse">Response message type for this call.</typeparam>
     public sealed class AsyncUnaryCall<TResponse> : IDisposable
     {
         readonly Task<TResponse> responseAsync;
@@ -48,7 +49,7 @@ namespace Grpc.Core
         readonly Func<Metadata> getTrailersFunc;
         readonly Action disposeAction;
 
-        public AsyncUnaryCall(Task<TResponse> responseAsync, Task<Metadata> responseHeadersAsync, Func<Status> getStatusFunc, Func<Metadata> getTrailersFunc, Action disposeAction)
+        internal AsyncUnaryCall(Task<TResponse> responseAsync, Task<Metadata> responseHeadersAsync, Func<Status> getStatusFunc, Func<Metadata> getTrailersFunc, Action disposeAction)
         {
             this.responseAsync = responseAsync;
             this.responseHeadersAsync = responseHeadersAsync;
diff --git a/src/csharp/Grpc.Core/CallInvocationDetails.cs b/src/csharp/Grpc.Core/CallInvocationDetails.cs
index 6565073fc5..8228b8f317 100644
--- a/src/csharp/Grpc.Core/CallInvocationDetails.cs
+++ b/src/csharp/Grpc.Core/CallInvocationDetails.cs
@@ -40,6 +40,8 @@ namespace Grpc.Core
     /// <summary>
     /// Details about a client-side call to be invoked.
     /// </summary>
+    /// <typeparam name="TRequest">Request message type for the call.</typeparam>
+    /// <typeparam name="TResponse">Response message type for the call.</typeparam>
     public struct CallInvocationDetails<TRequest, TResponse>
     {
         readonly Channel channel;
@@ -50,7 +52,7 @@ namespace Grpc.Core
         CallOptions options;
 
         /// <summary>
-        /// Initializes a new instance of the <see cref="Grpc.Core.CallInvocationDetails`2"/> struct.
+        /// Initializes a new instance of the <see cref="Grpc.Core.CallInvocationDetails{TRequest,TResponse}"/> struct.
         /// </summary>
         /// <param name="channel">Channel to use for this call.</param>
         /// <param name="method">Method to call.</param>
@@ -61,7 +63,7 @@ namespace Grpc.Core
         }
 
         /// <summary>
-        /// Initializes a new instance of the <see cref="Grpc.Core.CallInvocationDetails`2"/> struct.
+        /// Initializes a new instance of the <see cref="Grpc.Core.CallInvocationDetails{TRequest,TResponse}"/> struct.
         /// </summary>
         /// <param name="channel">Channel to use for this call.</param>
         /// <param name="method">Method to call.</param>
@@ -73,7 +75,7 @@ namespace Grpc.Core
         }
 
         /// <summary>
-        /// Initializes a new instance of the <see cref="Grpc.Core.CallInvocationDetails`2"/> struct.
+        /// Initializes a new instance of the <see cref="Grpc.Core.CallInvocationDetails{TRequest,TResponse}"/> struct.
         /// </summary>
         /// <param name="channel">Channel to use for this call.</param>
         /// <param name="method">Qualified method name.</param>
@@ -158,7 +160,7 @@ namespace Grpc.Core
         }
 
         /// <summary>
-        /// Returns new instance of <see cref="CallInvocationDetails"/> with
+        /// Returns new instance of <see cref="CallInvocationDetails{TRequest, TResponse}"/> with
         /// <c>Options</c> set to the value provided. Values of all other fields are preserved.
         /// </summary>
         public CallInvocationDetails<TRequest, TResponse> WithOptions(CallOptions options)
diff --git a/src/csharp/Grpc.Core/CallOptions.cs b/src/csharp/Grpc.Core/CallOptions.cs
index 3dfe80b48c..c3bc9c3156 100644
--- a/src/csharp/Grpc.Core/CallOptions.cs
+++ b/src/csharp/Grpc.Core/CallOptions.cs
@@ -118,6 +118,7 @@ namespace Grpc.Core
         /// Returns new instance of <see cref="CallOptions"/> with
         /// <c>Headers</c> set to the value provided. Values of all other fields are preserved.
         /// </summary>
+        /// <param name="headers">The headers.</param>
         public CallOptions WithHeaders(Metadata headers)
         {
             var newOptions = this;
@@ -129,6 +130,7 @@ namespace Grpc.Core
         /// Returns new instance of <see cref="CallOptions"/> with
         /// <c>Deadline</c> set to the value provided. Values of all other fields are preserved.
         /// </summary>
+        /// <param name="deadline">The deadline.</param>
         public CallOptions WithDeadline(DateTime deadline)
         {
             var newOptions = this;
@@ -140,6 +142,7 @@ namespace Grpc.Core
         /// Returns new instance of <see cref="CallOptions"/> with
         /// <c>CancellationToken</c> set to the value provided. Values of all other fields are preserved.
         /// </summary>
+        /// <param name="cancellationToken">The cancellation token.</param>
         public CallOptions WithCancellationToken(CancellationToken cancellationToken)
         {
             var newOptions = this;
diff --git a/src/csharp/Grpc.Core/Calls.cs b/src/csharp/Grpc.Core/Calls.cs
index e57ac89db3..94b3c2fe65 100644
--- a/src/csharp/Grpc.Core/Calls.cs
+++ b/src/csharp/Grpc.Core/Calls.cs
@@ -100,6 +100,7 @@ namespace Grpc.Core
         /// Invokes a client streaming call asynchronously.
         /// In client streaming scenario, client sends a stream of requests and server responds with a single response.
         /// </summary>
+        /// <param name="call">The call defintion.</param>
         /// <returns>An awaitable call object providing access to the response.</returns>
         /// <typeparam name="TRequest">Type of request messages.</typeparam>
         /// <typeparam name="TResponse">The of response message.</typeparam>
diff --git a/src/csharp/Grpc.Core/Channel.cs b/src/csharp/Grpc.Core/Channel.cs
index c11b320a64..f1942727cd 100644
--- a/src/csharp/Grpc.Core/Channel.cs
+++ b/src/csharp/Grpc.Core/Channel.cs
@@ -43,7 +43,9 @@ using Grpc.Core.Utils;
 namespace Grpc.Core
 {
     /// <summary>
-    /// gRPC Channel
+    /// Represents a gRPC channel. Channels are an abstraction of long-lived connections to remote servers.
+    /// More client objects can reuse the same channel. Creating a channel is an expensive operation compared to invoking
+    /// a remote call so in general you should reuse a single channel for as many calls as possible.
     /// </summary>
     public class Channel
     {
@@ -161,6 +163,7 @@ namespace Grpc.Core
         /// There is no need to call this explicitly unless your use case requires that.
         /// Starting an RPC on a new channel will request connection implicitly.
         /// </summary>
+        /// <param name="deadline">The deadline. <c>null</c> indicates no deadline.</param>
         public async Task ConnectAsync(DateTime? deadline = null)
         {
             var currentState = handle.CheckConnectivityState(true);
diff --git a/src/csharp/Grpc.Core/ChannelOptions.cs b/src/csharp/Grpc.Core/ChannelOptions.cs
index ad54b46ad5..f5ef63af54 100644
--- a/src/csharp/Grpc.Core/ChannelOptions.cs
+++ b/src/csharp/Grpc.Core/ChannelOptions.cs
@@ -44,9 +44,19 @@ namespace Grpc.Core
     /// </summary>
     public sealed class ChannelOption
     {
+        /// <summary>
+        /// Type of <c>ChannelOption</c>.
+        /// </summary>
         public enum OptionType
         {
+            /// <summary>
+            /// Channel option with integer value.
+            /// </summary>
             Integer,
+            
+            /// <summary>
+            /// Channel option with string value.
+            /// </summary>
             String
         }
 
@@ -79,6 +89,9 @@ namespace Grpc.Core
             this.intValue = intValue;
         }
 
+        /// <summary>
+        /// Gets the type of the <c>ChannelOption</c>.
+        /// </summary>
         public OptionType Type
         {
             get
@@ -87,6 +100,9 @@ namespace Grpc.Core
             }
         }
 
+        /// <summary>
+        /// Gets the name of the <c>ChannelOption</c>.
+        /// </summary>
         public string Name
         {
             get
@@ -95,6 +111,9 @@ namespace Grpc.Core
             }    
         }
 
+        /// <summary>
+        /// Gets the integer value the <c>ChannelOption</c>.
+        /// </summary>
         public int IntValue
         {
             get
@@ -104,6 +123,9 @@ namespace Grpc.Core
             }
         }
 
+        /// <summary>
+        /// Gets the string value the <c>ChannelOption</c>.
+        /// </summary>
         public string StringValue
         {
             get
@@ -140,7 +162,7 @@ namespace Grpc.Core
         /// <summary>Primary user agent: goes at the start of the user-agent metadata</summary>
         public const string PrimaryUserAgentString = "grpc.primary_user_agent";
 
-        /// <summary> Secondary user agent: goes at the end of the user-agent metadata</summary>
+        /// <summary>Secondary user agent: goes at the end of the user-agent metadata</summary>
         public const string SecondaryUserAgentString = "grpc.secondary_user_agent";
 
         /// <summary>
diff --git a/src/csharp/Grpc.Core/ClientBase.cs b/src/csharp/Grpc.Core/ClientBase.cs
index 903449439b..f4533e735c 100644
--- a/src/csharp/Grpc.Core/ClientBase.cs
+++ b/src/csharp/Grpc.Core/ClientBase.cs
@@ -53,6 +53,10 @@ namespace Grpc.Core
         readonly Channel channel;
         readonly string authUriBase;
 
+        /// <summary>
+        /// Initializes a new instance of <c>ClientBase</c> class.
+        /// </summary>
+        /// <param name="channel">The channel to use for remote call invocation.</param>
         public ClientBase(Channel channel)
         {
             this.channel = channel;
@@ -95,6 +99,11 @@ namespace Grpc.Core
         /// <summary>
         /// Creates a new call to given method.
         /// </summary>
+        /// <param name="method">The method to invoke.</param>
+        /// <param name="options">The call options.</param>
+        /// <typeparam name="TRequest">Request message type.</typeparam>
+        /// <typeparam name="TResponse">Response message type.</typeparam>
+        /// <returns>The call invocation details.</returns>
         protected CallInvocationDetails<TRequest, TResponse> CreateCall<TRequest, TResponse>(Method<TRequest, TResponse> method, CallOptions options)
             where TRequest : class
             where TResponse : class
diff --git a/src/csharp/Grpc.Core/ContextPropagationToken.cs b/src/csharp/Grpc.Core/ContextPropagationToken.cs
index a5bf1b5a70..1d899b97fd 100644
--- a/src/csharp/Grpc.Core/ContextPropagationToken.cs
+++ b/src/csharp/Grpc.Core/ContextPropagationToken.cs
@@ -44,8 +44,8 @@ namespace Grpc.Core
     /// In situations when a backend is making calls to another backend,
     /// it makes sense to propagate properties like deadline and cancellation 
     /// token of the server call to the child call.
-    /// C core provides some other contexts (like tracing context) that
-    /// are not accessible to C# layer, but this token still allows propagating them.
+    /// The gRPC native layer provides some other contexts (like tracing context) that
+    /// are not accessible to explicitly C# layer, but this token still allows propagating them.
     /// </summary>
     public class ContextPropagationToken
     {
@@ -143,13 +143,13 @@ namespace Grpc.Core
             this.propagateCancellation = propagateCancellation;
         }
             
-        /// <value><c>true</c> if parent call's deadline should be propagated to the child call.</value>
+        /// <summary><c>true</c> if parent call's deadline should be propagated to the child call.</summary>
         public bool IsPropagateDeadline
         {
             get { return this.propagateDeadline; }
         }
 
-        /// <value><c>true</c> if parent call's cancellation token should be propagated to the child call.</value>
+        /// <summary><c>true</c> if parent call's cancellation token should be propagated to the child call.</summary>
         public bool IsPropagateCancellation
         {
             get { return this.propagateCancellation; }
diff --git a/src/csharp/Grpc.Core/IAsyncStreamReader.cs b/src/csharp/Grpc.Core/IAsyncStreamReader.cs
index c0a0674e50..49e1ea7832 100644
--- a/src/csharp/Grpc.Core/IAsyncStreamReader.cs
+++ b/src/csharp/Grpc.Core/IAsyncStreamReader.cs
@@ -42,7 +42,7 @@ namespace Grpc.Core
     /// <summary>
     /// A stream of messages to be read.
     /// </summary>
-    /// <typeparam name="T"></typeparam>
+    /// <typeparam name="T">The message type.</typeparam>
     public interface IAsyncStreamReader<T> : IAsyncEnumerator<T>
     {
         // TODO(jtattermusch): consider just using IAsyncEnumerator instead of this interface.
diff --git a/src/csharp/Grpc.Core/IAsyncStreamWriter.cs b/src/csharp/Grpc.Core/IAsyncStreamWriter.cs
index 4e2acb9c71..9c0d2d312e 100644
--- a/src/csharp/Grpc.Core/IAsyncStreamWriter.cs
+++ b/src/csharp/Grpc.Core/IAsyncStreamWriter.cs
@@ -42,7 +42,7 @@ namespace Grpc.Core
     /// <summary>
     /// A writable stream of messages.
     /// </summary>
-    /// <typeparam name="T"></typeparam>
+    /// <typeparam name="T">The message type.</typeparam>
     public interface IAsyncStreamWriter<T>
     {
         /// <summary>
@@ -56,7 +56,7 @@ namespace Grpc.Core
         /// If null, default options will be used.
         /// Once set, this property maintains its value across subsequent
         /// writes.
-        /// <value>The write options.</value>
+        /// </summary>
         WriteOptions WriteOptions { get; set; }
     }
 }
diff --git a/src/csharp/Grpc.Core/IClientStreamWriter.cs b/src/csharp/Grpc.Core/IClientStreamWriter.cs
index a3028bc374..3fd0774db5 100644
--- a/src/csharp/Grpc.Core/IClientStreamWriter.cs
+++ b/src/csharp/Grpc.Core/IClientStreamWriter.cs
@@ -42,7 +42,7 @@ namespace Grpc.Core
     /// <summary>
     /// Client-side writable stream of messages with Close capability.
     /// </summary>
-    /// <typeparam name="T"></typeparam>
+    /// <typeparam name="T">The message type.</typeparam>
     public interface IClientStreamWriter<T> : IAsyncStreamWriter<T>
     {
         /// <summary>
diff --git a/src/csharp/Grpc.Core/Internal/CallSafeHandle.cs b/src/csharp/Grpc.Core/Internal/CallSafeHandle.cs
index 0f187529e8..c3611a7761 100644
--- a/src/csharp/Grpc.Core/Internal/CallSafeHandle.cs
+++ b/src/csharp/Grpc.Core/Internal/CallSafeHandle.cs
@@ -38,7 +38,7 @@ using Grpc.Core.Utils;
 namespace Grpc.Core.Internal
 {
     /// <summary>
-    /// grpc_call from <grpc/grpc.h>
+    /// grpc_call from <c>grpc/grpc.h</c>
     /// </summary>
     internal class CallSafeHandle : SafeHandleZeroIsInvalid, INativeCall
     {
diff --git a/src/csharp/Grpc.Core/Internal/ChannelArgsSafeHandle.cs b/src/csharp/Grpc.Core/Internal/ChannelArgsSafeHandle.cs
index c12aec5a3a..ea5b52374e 100644
--- a/src/csharp/Grpc.Core/Internal/ChannelArgsSafeHandle.cs
+++ b/src/csharp/Grpc.Core/Internal/ChannelArgsSafeHandle.cs
@@ -35,7 +35,7 @@ using System.Threading.Tasks;
 namespace Grpc.Core.Internal
 {
     /// <summary>
-    /// grpc_channel_args from <grpc/grpc.h>
+    /// grpc_channel_args from <c>grpc/grpc.h</c>
     /// </summary>
     internal class ChannelArgsSafeHandle : SafeHandleZeroIsInvalid
     {
diff --git a/src/csharp/Grpc.Core/Internal/ChannelSafeHandle.cs b/src/csharp/Grpc.Core/Internal/ChannelSafeHandle.cs
index 8cef566c14..7a1c6e3dac 100644
--- a/src/csharp/Grpc.Core/Internal/ChannelSafeHandle.cs
+++ b/src/csharp/Grpc.Core/Internal/ChannelSafeHandle.cs
@@ -36,7 +36,7 @@ using System.Threading.Tasks;
 namespace Grpc.Core.Internal
 {
     /// <summary>
-    /// grpc_channel from <grpc/grpc.h>
+    /// grpc_channel from <c>grpc/grpc.h</c>
     /// </summary>
     internal class ChannelSafeHandle : SafeHandleZeroIsInvalid
     {
diff --git a/src/csharp/Grpc.Core/Internal/CompletionQueueSafeHandle.cs b/src/csharp/Grpc.Core/Internal/CompletionQueueSafeHandle.cs
index f64f3d4175..f7a3471bb4 100644
--- a/src/csharp/Grpc.Core/Internal/CompletionQueueSafeHandle.cs
+++ b/src/csharp/Grpc.Core/Internal/CompletionQueueSafeHandle.cs
@@ -35,7 +35,7 @@ using System.Threading.Tasks;
 namespace Grpc.Core.Internal
 {
     /// <summary>
-    /// grpc_completion_queue from <grpc/grpc.h>
+    /// grpc_completion_queue from <c>grpc/grpc.h</c>
     /// </summary>
     internal class CompletionQueueSafeHandle : SafeHandleZeroIsInvalid
     {
diff --git a/src/csharp/Grpc.Core/Internal/CredentialsSafeHandle.cs b/src/csharp/Grpc.Core/Internal/CredentialsSafeHandle.cs
index 8b4fa85e5d..feed335362 100644
--- a/src/csharp/Grpc.Core/Internal/CredentialsSafeHandle.cs
+++ b/src/csharp/Grpc.Core/Internal/CredentialsSafeHandle.cs
@@ -36,7 +36,7 @@ using System.Threading.Tasks;
 namespace Grpc.Core.Internal
 {
     /// <summary>
-    /// grpc_credentials from <grpc/grpc_security.h>
+    /// grpc_credentials from <c>grpc/grpc_security.h</c>
     /// </summary>
     internal class CredentialsSafeHandle : SafeHandleZeroIsInvalid
     {
diff --git a/src/csharp/Grpc.Core/Internal/MetadataArraySafeHandle.cs b/src/csharp/Grpc.Core/Internal/MetadataArraySafeHandle.cs
index 83994f6762..31b834c979 100644
--- a/src/csharp/Grpc.Core/Internal/MetadataArraySafeHandle.cs
+++ b/src/csharp/Grpc.Core/Internal/MetadataArraySafeHandle.cs
@@ -35,7 +35,7 @@ using System.Threading.Tasks;
 namespace Grpc.Core.Internal
 {
     /// <summary>
-    /// grpc_metadata_array from <grpc/grpc.h>
+    /// grpc_metadata_array from <c>grpc/grpc.h</c>
     /// </summary>
     internal class MetadataArraySafeHandle : SafeHandleZeroIsInvalid
     {
diff --git a/src/csharp/Grpc.Core/Internal/ServerCredentialsSafeHandle.cs b/src/csharp/Grpc.Core/Internal/ServerCredentialsSafeHandle.cs
index 37a4f5256b..51e352a18b 100644
--- a/src/csharp/Grpc.Core/Internal/ServerCredentialsSafeHandle.cs
+++ b/src/csharp/Grpc.Core/Internal/ServerCredentialsSafeHandle.cs
@@ -37,7 +37,7 @@ using Grpc.Core.Utils;
 namespace Grpc.Core.Internal
 {
     /// <summary>
-    /// grpc_server_credentials from <grpc/grpc_security.h>
+    /// grpc_server_credentials from <c>grpc/grpc_security.h</c>
     /// </summary>
     internal class ServerCredentialsSafeHandle : SafeHandleZeroIsInvalid
     {
diff --git a/src/csharp/Grpc.Core/Metadata.cs b/src/csharp/Grpc.Core/Metadata.cs
index a589b50caa..99fe0b5478 100644
--- a/src/csharp/Grpc.Core/Metadata.cs
+++ b/src/csharp/Grpc.Core/Metadata.cs
@@ -41,7 +41,13 @@ using Grpc.Core.Utils;
 namespace Grpc.Core
 {
     /// <summary>
-    /// Provides access to read and write metadata values to be exchanged during a call.
+    /// A collection of metadata entries that can be exchanged during a call.
+    /// gRPC supports these types of metadata:
+    /// <list type="bullet">
+    /// <item><term>Request headers</term><description>are sent by the client at the beginning of a remote call before any request messages are sent.</description></item>
+    /// <item><term>Response headers</term><description>are sent by the server at the beginning of a remote call handler before any response messages are sent.</description></item>
+    /// <item><term>Response trailers</term><description>are sent by the server at the end of a remote call along with resulting call status.</description></item>
+    /// </list>
     /// </summary>
     public sealed class Metadata : IList<Metadata.Entry>
     {
@@ -58,21 +64,19 @@ namespace Grpc.Core
         readonly List<Entry> entries;
         bool readOnly;
 
+        /// <summary>
+        /// Initializes a new instance of <c>Metadata</c>.
+        /// </summary>
         public Metadata()
         {
             this.entries = new List<Entry>();
         }
 
-        public Metadata(ICollection<Entry> entries)
-        {
-            this.entries = new List<Entry>(entries);
-        }
-
         /// <summary>
         /// Makes this object read-only.
         /// </summary>
         /// <returns>this object</returns>
-        public Metadata Freeze()
+        internal Metadata Freeze()
         {
             this.readOnly = true;
             return this;
@@ -197,7 +201,7 @@ namespace Grpc.Core
             }
 
             /// <summary>
-            /// Initializes a new instance of the <see cref="Grpc.Core.Metadata+Entry"/> struct with a binary value.
+            /// Initializes a new instance of the <see cref="Grpc.Core.Metadata.Entry"/> struct with a binary value.
             /// </summary>
             /// <param name="key">Metadata key, needs to have suffix indicating a binary valued metadata entry.</param>
             /// <param name="valueBytes">Value bytes.</param>
@@ -213,7 +217,7 @@ namespace Grpc.Core
             }
 
             /// <summary>
-            /// Initializes a new instance of the <see cref="Grpc.Core.Metadata+Entry"/> struct holding an ASCII value.
+            /// Initializes a new instance of the <see cref="Grpc.Core.Metadata.Entry"/> struct holding an ASCII value.
             /// </summary>
             /// <param name="key">Metadata key, must not use suffix indicating a binary valued metadata entry.</param>
             /// <param name="value">Value string. Only ASCII characters are allowed.</param>
@@ -280,7 +284,7 @@ namespace Grpc.Core
             }
 
             /// <summary>
-            /// Returns a <see cref="System.String"/> that represents the current <see cref="Grpc.Core.Metadata+Entry"/>.
+            /// Returns a <see cref="System.String"/> that represents the current <see cref="Grpc.Core.Metadata.Entry"/>.
             /// </summary>
             public override string ToString()
             {
diff --git a/src/csharp/Grpc.Core/Method.cs b/src/csharp/Grpc.Core/Method.cs
index 4c53285893..99162a7d5d 100644
--- a/src/csharp/Grpc.Core/Method.cs
+++ b/src/csharp/Grpc.Core/Method.cs
@@ -84,6 +84,8 @@ namespace Grpc.Core
     /// <summary>
     /// A description of a remote method.
     /// </summary>
+    /// <typeparam name="TRequest">Request message type for this method.</typeparam>
+    /// <typeparam name="TResponse">Response message type for this method.</typeparam>
     public class Method<TRequest, TResponse> : IMethod
     {
         readonly MethodType type;
diff --git a/src/csharp/Grpc.Core/Server.cs b/src/csharp/Grpc.Core/Server.cs
index 28f1686e20..7c94d21561 100644
--- a/src/csharp/Grpc.Core/Server.cs
+++ b/src/csharp/Grpc.Core/Server.cs
@@ -44,7 +44,7 @@ using Grpc.Core.Utils;
 namespace Grpc.Core
 {
     /// <summary>
-    /// A gRPC server.
+    /// gRPC server. A single server can server arbitrary number of services and can listen on more than one ports.
     /// </summary>
     public class Server
     {
@@ -324,6 +324,9 @@ namespace Grpc.Core
                 server.AddServiceDefinitionInternal(serviceDefinition);
             }
 
+            /// <summary>
+            /// Gets enumerator for this collection.
+            /// </summary>
             public IEnumerator<ServerServiceDefinition> GetEnumerator()
             {
                 return server.serviceDefinitionsList.GetEnumerator();
@@ -369,6 +372,9 @@ namespace Grpc.Core
                 return Add(new ServerPort(host, port, credentials));
             }
 
+            /// <summary>
+            /// Gets enumerator for this collection.
+            /// </summary>
             public IEnumerator<ServerPort> GetEnumerator()
             {
                 return server.serverPortList.GetEnumerator();
diff --git a/src/csharp/Grpc.Core/ServerCallContext.cs b/src/csharp/Grpc.Core/ServerCallContext.cs
index 75d81c64f3..09a6b882a6 100644
--- a/src/csharp/Grpc.Core/ServerCallContext.cs
+++ b/src/csharp/Grpc.Core/ServerCallContext.cs
@@ -72,6 +72,13 @@ namespace Grpc.Core
             this.writeOptionsHolder = writeOptionsHolder;
         }
 
+        /// <summary>
+        /// Asynchronously sends response headers for the current call to the client. This method may only be invoked once for each call and needs to be invoked
+        /// before any response messages are written. Writing the first response message implicitly sends empty response headers if <c>WriteResponseHeadersAsync</c> haven't
+        /// been called yet.
+        /// </summary>
+        /// <param name="responseHeaders">The response headers to send.</param>
+        /// <returns>The task that finished once response headers have been written.</returns>
         public Task WriteResponseHeadersAsync(Metadata responseHeaders)
         {
             return writeHeadersFunc(responseHeaders);
@@ -186,6 +193,9 @@ namespace Grpc.Core
     /// </summary>
     public interface IHasWriteOptions
     {
+        /// <summary>
+        /// Gets or sets the write options.
+        /// </summary>
         WriteOptions WriteOptions { get; set; }
     }
 }
diff --git a/src/csharp/Grpc.Core/ServerMethods.cs b/src/csharp/Grpc.Core/ServerMethods.cs
index 1f119a80ff..728f77cde5 100644
--- a/src/csharp/Grpc.Core/ServerMethods.cs
+++ b/src/csharp/Grpc.Core/ServerMethods.cs
@@ -38,6 +38,8 @@ namespace Grpc.Core
     /// <summary>
     /// Server-side handler for unary call.
     /// </summary>
+    /// <typeparam name="TRequest">Request message type for this method.</typeparam>
+    /// <typeparam name="TResponse">Response message type for this method.</typeparam>
     public delegate Task<TResponse> UnaryServerMethod<TRequest, TResponse>(TRequest request, ServerCallContext context)
         where TRequest : class
         where TResponse : class;
@@ -45,6 +47,8 @@ namespace Grpc.Core
     /// <summary>
     /// Server-side handler for client streaming call.
     /// </summary>
+    /// <typeparam name="TRequest">Request message type for this method.</typeparam>
+    /// <typeparam name="TResponse">Response message type for this method.</typeparam>
     public delegate Task<TResponse> ClientStreamingServerMethod<TRequest, TResponse>(IAsyncStreamReader<TRequest> requestStream, ServerCallContext context)
         where TRequest : class
         where TResponse : class;
@@ -52,6 +56,8 @@ namespace Grpc.Core
     /// <summary>
     /// Server-side handler for server streaming call.
     /// </summary>
+    /// <typeparam name="TRequest">Request message type for this method.</typeparam>
+    /// <typeparam name="TResponse">Response message type for this method.</typeparam>
     public delegate Task ServerStreamingServerMethod<TRequest, TResponse>(TRequest request, IServerStreamWriter<TResponse> responseStream, ServerCallContext context)
         where TRequest : class
         where TResponse : class;
@@ -59,6 +65,8 @@ namespace Grpc.Core
     /// <summary>
     /// Server-side handler for bidi streaming call.
     /// </summary>
+    /// <typeparam name="TRequest">Request message type for this method.</typeparam>
+    /// <typeparam name="TResponse">Response message type for this method.</typeparam>
     public delegate Task DuplexStreamingServerMethod<TRequest, TResponse>(IAsyncStreamReader<TRequest> requestStream, IServerStreamWriter<TResponse> responseStream, ServerCallContext context)
         where TRequest : class
         where TResponse : class;
diff --git a/src/csharp/Grpc.Core/ServerServiceDefinition.cs b/src/csharp/Grpc.Core/ServerServiceDefinition.cs
index 94b0a320c3..deb1431ca3 100644
--- a/src/csharp/Grpc.Core/ServerServiceDefinition.cs
+++ b/src/csharp/Grpc.Core/ServerServiceDefinition.cs
@@ -40,6 +40,8 @@ namespace Grpc.Core
 {
     /// <summary>
     /// Mapping of method names to server call handlers.
+    /// Normally, the <c>ServerServiceDefinition</c> objects will be created by the <c>BindService</c> factory method 
+    /// that is part of the autogenerated code for a protocol buffers service definition.
     /// </summary>
     public class ServerServiceDefinition
     {
@@ -58,21 +60,41 @@ namespace Grpc.Core
             }
         }
 
+        /// <summary>
+        /// Creates a new builder object for <c>ServerServiceDefinition</c>.
+        /// </summary>
+        /// <param name="serviceName">The service name.</param>
+        /// <returns>The builder object.</returns>
         public static Builder CreateBuilder(string serviceName)
         {
             return new Builder(serviceName);
         }
 
+        /// <summary>
+        /// Builder class for <see cref="ServerServiceDefinition"/>.
+        /// </summary>
         public class Builder
         {
             readonly string serviceName;
             readonly Dictionary<string, IServerCallHandler> callHandlers = new Dictionary<string, IServerCallHandler>();
 
+            /// <summary>
+            /// Creates a new instance of builder.
+            /// </summary>
+            /// <param name="serviceName">The service name.</param>
             public Builder(string serviceName)
             {
                 this.serviceName = serviceName;
             }
 
+            /// <summary>
+            /// Adds a definitions for a single request - single response method.
+            /// </summary>
+            /// <typeparam name="TRequest">The request message class.</typeparam>
+            /// <typeparam name="TResponse">The response message class.</typeparam>
+            /// <param name="method">The method.</param>
+            /// <param name="handler">The method handler.</param>
+            /// <returns>This builder instance.</returns>
             public Builder AddMethod<TRequest, TResponse>(
                 Method<TRequest, TResponse> method,
                 UnaryServerMethod<TRequest, TResponse> handler)
@@ -83,6 +105,14 @@ namespace Grpc.Core
                 return this;
             }
 
+            /// <summary>
+            /// Adds a definitions for a client streaming method.
+            /// </summary>
+            /// <typeparam name="TRequest">The request message class.</typeparam>
+            /// <typeparam name="TResponse">The response message class.</typeparam>
+            /// <param name="method">The method.</param>
+            /// <param name="handler">The method handler.</param>
+            /// <returns>This builder instance.</returns>
             public Builder AddMethod<TRequest, TResponse>(
                 Method<TRequest, TResponse> method,
                 ClientStreamingServerMethod<TRequest, TResponse> handler)
@@ -93,6 +123,14 @@ namespace Grpc.Core
                 return this;
             }
 
+            /// <summary>
+            /// Adds a definitions for a server streaming method.
+            /// </summary>
+            /// <typeparam name="TRequest">The request message class.</typeparam>
+            /// <typeparam name="TResponse">The response message class.</typeparam>
+            /// <param name="method">The method.</param>
+            /// <param name="handler">The method handler.</param>
+            /// <returns>This builder instance.</returns>
             public Builder AddMethod<TRequest, TResponse>(
                 Method<TRequest, TResponse> method,
                 ServerStreamingServerMethod<TRequest, TResponse> handler)
@@ -103,6 +141,14 @@ namespace Grpc.Core
                 return this;
             }
 
+            /// <summary>
+            /// Adds a definitions for a bidirectional streaming method.
+            /// </summary>
+            /// <typeparam name="TRequest">The request message class.</typeparam>
+            /// <typeparam name="TResponse">The response message class.</typeparam>
+            /// <param name="method">The method.</param>
+            /// <param name="handler">The method handler.</param>
+            /// <returns>This builder instance.</returns>
             public Builder AddMethod<TRequest, TResponse>(
                 Method<TRequest, TResponse> method,
                 DuplexStreamingServerMethod<TRequest, TResponse> handler)
@@ -113,6 +159,10 @@ namespace Grpc.Core
                 return this;
             }
 
+            /// <summary>
+            /// Creates an immutable <c>ServerServiceDefinition</c> from this builder.
+            /// </summary>
+            /// <returns>The <c>ServerServiceDefinition</c> object.</returns>
             public ServerServiceDefinition Build()
             {
                 return new ServerServiceDefinition(callHandlers);
diff --git a/src/csharp/Grpc.Core/Utils/Preconditions.cs b/src/csharp/Grpc.Core/Utils/Preconditions.cs
index 374262f87a..a8ab603391 100644
--- a/src/csharp/Grpc.Core/Utils/Preconditions.cs
+++ b/src/csharp/Grpc.Core/Utils/Preconditions.cs
@@ -43,6 +43,7 @@ namespace Grpc.Core.Utils
         /// <summary>
         /// Throws <see cref="ArgumentException"/> if condition is false.
         /// </summary>
+        /// <param name="condition">The condition.</param>
         public static void CheckArgument(bool condition)
         {
             if (!condition)
@@ -54,6 +55,8 @@ namespace Grpc.Core.Utils
         /// <summary>
         /// Throws <see cref="ArgumentException"/> with given message if condition is false.
         /// </summary>
+        /// <param name="condition">The condition.</param>
+        /// <param name="errorMessage">The error message.</param>
         public static void CheckArgument(bool condition, string errorMessage)
         {
             if (!condition)
@@ -65,6 +68,7 @@ namespace Grpc.Core.Utils
         /// <summary>
         /// Throws <see cref="ArgumentNullException"/> if reference is null.
         /// </summary>
+        /// <param name="reference">The reference.</param>
         public static T CheckNotNull<T>(T reference)
         {
             if (reference == null)
@@ -77,6 +81,8 @@ namespace Grpc.Core.Utils
         /// <summary>
         /// Throws <see cref="ArgumentNullException"/> if reference is null.
         /// </summary>
+        /// <param name="reference">The reference.</param>
+        /// <param name="paramName">The parameter name.</param>
         public static T CheckNotNull<T>(T reference, string paramName)
         {
             if (reference == null)
@@ -89,6 +95,7 @@ namespace Grpc.Core.Utils
         /// <summary>
         /// Throws <see cref="InvalidOperationException"/> if condition is false.
         /// </summary>
+        /// <param name="condition">The condition.</param>
         public static void CheckState(bool condition)
         {
             if (!condition)
@@ -100,6 +107,8 @@ namespace Grpc.Core.Utils
         /// <summary>
         /// Throws <see cref="InvalidOperationException"/> with given message if condition is false.
         /// </summary>
+        /// <param name="condition">The condition.</param>
+        /// <param name="errorMessage">The error message.</param>
         public static void CheckState(bool condition, string errorMessage)
         {
             if (!condition)
diff --git a/src/csharp/Grpc.Core/WriteOptions.cs b/src/csharp/Grpc.Core/WriteOptions.cs
index 7ef3189d76..7523ada84a 100644
--- a/src/csharp/Grpc.Core/WriteOptions.cs
+++ b/src/csharp/Grpc.Core/WriteOptions.cs
@@ -66,11 +66,18 @@ namespace Grpc.Core
             
         private WriteFlags flags;
 
+        /// <summary>
+        /// Initializes a new instance of <c>WriteOptions</c> class.
+        /// </summary>
+        /// <param name="flags">The write flags.</param>
         public WriteOptions(WriteFlags flags = default(WriteFlags))
         {
             this.flags = flags;
         }
 
+        /// <summary>
+        /// Gets the write flags.
+        /// </summary>
         public WriteFlags Flags
         {
             get
diff --git a/src/csharp/Grpc.HealthCheck/HealthServiceImpl.cs b/src/csharp/Grpc.HealthCheck/HealthServiceImpl.cs
index 3c3b9c35f1..8c04b43a86 100644
--- a/src/csharp/Grpc.HealthCheck/HealthServiceImpl.cs
+++ b/src/csharp/Grpc.HealthCheck/HealthServiceImpl.cs
@@ -95,6 +95,12 @@ namespace Grpc.HealthCheck
             }
         }
 
+        /// <summary>
+        /// Performs a health status check.
+        /// </summary>
+        /// <param name="request">The check request.</param>
+        /// <param name="context">The call context.</param>
+        /// <returns>The asynchronous response.</returns>
         public Task<HealthCheckResponse> Check(HealthCheckRequest request, ServerCallContext context)
         {
             lock (myLock)
diff --git a/src/csharp/doc/grpc_csharp_public.shfbproj b/src/csharp/doc/grpc_csharp_public.shfbproj
index 05c93f4a13..d9b9749819 100644
--- a/src/csharp/doc/grpc_csharp_public.shfbproj
+++ b/src/csharp/doc/grpc_csharp_public.shfbproj
@@ -18,7 +18,8 @@
     <Language>en-US</Language>
     <DocumentationSources>
       <DocumentationSource sourceFile="..\Grpc.Auth\Grpc.Auth.csproj" />
-<DocumentationSource sourceFile="..\Grpc.Core\Grpc.Core.csproj" /></DocumentationSources>
+      <DocumentationSource sourceFile="..\Grpc.Core\Grpc.Core.csproj" />
+    </DocumentationSources>
     <BuildAssemblerVerbosity>OnlyWarningsAndErrors</BuildAssemblerVerbosity>
     <HelpFileFormat>Website</HelpFileFormat>
     <IndentHtml>False</IndentHtml>
@@ -37,6 +38,15 @@
     <HelpTitle>gRPC C#</HelpTitle>
     <ContentPlacement>AboveNamespaces</ContentPlacement>
     <HtmlHelpName>Documentation</HtmlHelpName>
+    <NamespaceSummaries>
+      <NamespaceSummaryItem name="Grpc.Auth" isDocumented="True">Provides OAuth2 based authentication for gRPC. &lt;c&gt;Grpc.Auth&lt;/c&gt; currently consists of a set of very lightweight wrappers and uses C# &lt;a href="https://www.nuget.org/packages/Google.Apis.Auth/"&gt;Google.Apis.Auth&lt;/a&gt; library.</NamespaceSummaryItem>
+<NamespaceSummaryItem name="Grpc.Core" isDocumented="True">Main namespace for gRPC C# functionality. Contains concepts representing both client side and server side gRPC logic.
+
+&lt;seealso cref="Grpc.Core.Channel"/&gt; 
+&lt;seealso cref="Grpc.Core.Server"/&gt;</NamespaceSummaryItem>
+<NamespaceSummaryItem name="Grpc.Core.Logging" isDocumented="True">Provides functionality to redirect gRPC logs to application-specified destination.</NamespaceSummaryItem>
+<NamespaceSummaryItem name="Grpc.Core.Utils" isDocumented="True">Various utilities for gRPC C#.</NamespaceSummaryItem></NamespaceSummaries>
+    <MissingTags>Summary, Parameter, AutoDocumentCtors, Namespace, TypeParameter, AutoDocumentDispose</MissingTags>
   </PropertyGroup>
   <!-- There are no properties for these groups.  AnyCPU needs to appear in order for Visual Studio to perform
 			 the build.  The others are optional common platform types that may appear. -->