diff options
| author |  Jan Tattermusch <jtattermusch@google.com> | 2015-08-24 16:43:23 -0700 |
|---|---|---|
| committer | Jan Tattermusch <jtattermusch@google.com> | 2015-08-24 17:41:21 -0700 |
| commit | 12855fc68201962311ba1474243809e2d3953964 (patch) | |
| tree | 11f9ea2d56316b898dde9dba659bc9d3df18014c | |
| parent | f637573b95b73400e81e038176451fb4c466e523 (diff) | |
polishing public docs
32 files changed, 191 insertions, 27 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 6036f4c7bb..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; diff --git a/src/csharp/Grpc.Core/AsyncDuplexStreamingCall.cs b/src/csharp/Grpc.Core/AsyncDuplexStreamingCall.cs index ea7cb4727b..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; diff --git a/src/csharp/Grpc.Core/AsyncServerStreamingCall.cs b/src/csharp/Grpc.Core/AsyncServerStreamingCall.cs index d00fa8defd..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; diff --git a/src/csharp/Grpc.Core/AsyncUnaryCall.cs b/src/csharp/Grpc.Core/AsyncUnaryCall.cs index fb51bd65e7..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; 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 79d25696a1..99fe0b5478 100644 --- a/src/csharp/Grpc.Core/Metadata.cs +++ b/src/csharp/Grpc.Core/Metadata.cs @@ -42,6 +42,12 @@ namespace Grpc.Core { /// <summary> /// 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> { @@ -195,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> @@ -211,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> @@ -278,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. <c>Grpc.Auth</c> currently consists of a set of very lightweight wrappers and uses C# <a href="https://www.nuget.org/packages/Google.Apis.Auth/">Google.Apis.Auth</a> 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. + +<seealso cref="Grpc.Core.Channel"/> +<seealso cref="Grpc.Core.Server"/></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. --> |