fixing doc comments

pull/2872/head
Jan Tattermusch 9 years ago
parent 3e941977f5
commit 66eb18dcc7
  1. 2
      src/csharp/Grpc.Core/Calls.cs
  2. 18
      src/csharp/Grpc.Core/GrpcEnvironment.cs
  3. 13
      src/csharp/Grpc.Core/Logging/ConsoleLogger.cs
  4. 6
      src/csharp/Grpc.Core/Logging/ILogger.cs
  5. 19
      src/csharp/Grpc.Core/Marshaller.cs
  6. 52
      src/csharp/Grpc.Core/Method.cs
  7. 14
      src/csharp/Grpc.Core/RpcException.cs
  8. 4
      src/csharp/Grpc.Core/ServerMethods.cs
  9. 8
      src/csharp/Grpc.Core/ServerServiceDefinition.cs
  10. 13
      src/csharp/Grpc.Core/Status.cs
  11. 156
      src/csharp/Grpc.Core/StatusCode.cs
  12. 3
      src/csharp/Grpc.Core/Utils/BenchmarkUtil.cs
  13. 34
      src/csharp/Grpc.Core/Version.cs
  14. 37
      src/csharp/Grpc.Core/VersionInfo.cs

@ -31,8 +31,6 @@
#endregion
using System;
using System.Threading;
using System.Threading.Tasks;
using Grpc.Core.Internal;

@ -192,23 +192,5 @@ namespace Grpc.Core
Logger.Info("gRPC shutdown.");
}
/// <summary>
/// Shuts down this environment asynchronously.
/// </summary>
private Task CloseAsync()
{
return Task.Run(() =>
{
try
{
Close();
}
catch (Exception e)
{
Logger.Error(e, "Error occured while shutting down GrpcEnvironment.");
}
});
}
}
}

@ -42,16 +42,21 @@ namespace Grpc.Core.Logging
readonly Type forType;
readonly string forTypeString;
/// <summary>Creates a console logger not associated to any specific type.</summary>
public ConsoleLogger() : this(null)
{
}
/// <summary>Creates a console logger that logs messsage specific for given type.</summary>
private ConsoleLogger(Type forType)
{
this.forType = forType;
this.forTypeString = forType != null ? forType.FullName + " " : "";
}
/// <summary>
/// Returns a logger associated with the specified type.
/// </summary>
public ILogger ForType<T>()
{
if (typeof(T) == forType)
@ -61,31 +66,37 @@ namespace Grpc.Core.Logging
return new ConsoleLogger(typeof(T));
}
/// <summary>Logs a message with severity Debug.</summary>
public void Debug(string message, params object[] formatArgs)
{
Log("D", message, formatArgs);
}
/// <summary>Logs a message with severity Info.</summary>
public void Info(string message, params object[] formatArgs)
{
Log("I", message, formatArgs);
}
/// <summary>Logs a message with severity Warning.</summary>
public void Warning(string message, params object[] formatArgs)
{
Log("W", message, formatArgs);
}
/// <summary>Logs a message and an associated exception with severity Warning.</summary>
public void Warning(Exception exception, string message, params object[] formatArgs)
{
Log("W", message + " " + exception, formatArgs);
}
/// <summary>Logs a message with severity Error.</summary>
public void Error(string message, params object[] formatArgs)
{
Log("E", message, formatArgs);
}
/// <summary>Logs a message and an associated exception with severity Error.</summary>
public void Error(Exception exception, string message, params object[] formatArgs)
{
Log("E", message + " " + exception, formatArgs);

@ -42,16 +42,22 @@ namespace Grpc.Core.Logging
/// <summary>Returns a logger associated with the specified type.</summary>
ILogger ForType<T>();
/// <summary>Logs a message with severity Debug.</summary>
void Debug(string message, params object[] formatArgs);
/// <summary>Logs a message with severity Info.</summary>
void Info(string message, params object[] formatArgs);
/// <summary>Logs a message with severity Warning.</summary>
void Warning(string message, params object[] formatArgs);
/// <summary>Logs a message and an associated exception with severity Warning.</summary>
void Warning(Exception exception, string message, params object[] formatArgs);
/// <summary>Logs a message with severity Error.</summary>
void Error(string message, params object[] formatArgs);
/// <summary>Logs a message and an associated exception with severity Error.</summary>
void Error(Exception exception, string message, params object[] formatArgs);
}
}

@ -37,19 +37,27 @@ using Grpc.Core.Utils;
namespace Grpc.Core
{
/// <summary>
/// For serializing and deserializing messages.
/// Encapsulates the logic for serializing and deserializing messages.
/// </summary>
public struct Marshaller<T>
{
readonly Func<T, byte[]> serializer;
readonly Func<byte[], T> deserializer;
/// <summary>
/// Initializes a new marshaller.
/// </summary>
/// <param name="serializer">Function that will be used to serialize messages.</param>
/// <param name="deserializer">Function that will be used to deserialize messages.</param>
public Marshaller(Func<T, byte[]> serializer, Func<byte[], T> deserializer)
{
this.serializer = Preconditions.CheckNotNull(serializer, "serializer");
this.deserializer = Preconditions.CheckNotNull(deserializer, "deserializer");
}
/// <summary>
/// Gets the serializer function.
/// </summary>
public Func<T, byte[]> Serializer
{
get
@ -58,6 +66,9 @@ namespace Grpc.Core
}
}
/// <summary>
/// Gets the deserializer function.
/// </summary>
public Func<byte[], T> Deserializer
{
get
@ -72,11 +83,17 @@ namespace Grpc.Core
/// </summary>
public static class Marshallers
{
/// <summary>
/// Creates a marshaller from specified serializer and deserializer.
/// </summary>
public static Marshaller<T> Create<T>(Func<T, byte[]> serializer, Func<byte[], T> deserializer)
{
return new Marshaller<T>(serializer, deserializer);
}
/// <summary>
/// Returns a marshaller for <c>string</c> type. This is useful for testing.
/// </summary>
public static Marshaller<string> StringMarshaller
{
get

@ -41,14 +41,21 @@ namespace Grpc.Core
/// </summary>
public enum MethodType
{
Unary, // Unary request, unary response.
ClientStreaming, // Streaming request, unary response.
ServerStreaming, // Unary request, streaming response.
DuplexStreaming // Streaming request, streaming response.
/// <summary>Single request sent from client, single response received from server.</summary>
Unary,
/// <summary>Stream of request sent from client, single response received from server.</summary>
ClientStreaming,
/// <summary>Single request sent from client, stream of responses received from server.</summary>
ServerStreaming,
/// <summary>Both server and client can stream arbitrary number of requests and responses simultaneously.</summary>
DuplexStreaming
}
/// <summary>
/// A description of a service method.
/// A description of a remote method.
/// </summary>
public class Method<TRequest, TResponse>
{
@ -59,6 +66,14 @@ namespace Grpc.Core
readonly Marshaller<TResponse> responseMarshaller;
readonly string fullName;
/// <summary>
/// Initializes a new instance of the <c>Method</c> class.
/// </summary>
/// <param name="type">Type of method.</param>
/// <param name="serviceName">Name of service this method belongs to.</param>
/// <param name="name">Unqualified name of the method.</param>
/// <param name="requestMarshaller">Marshaller used for request messages.</param>
/// <param name="responseMarshaller">Marshaller used for response messages.</param>
public Method(MethodType type, string serviceName, string name, Marshaller<TRequest> requestMarshaller, Marshaller<TResponse> responseMarshaller)
{
this.type = type;
@ -66,9 +81,12 @@ namespace Grpc.Core
this.name = Preconditions.CheckNotNull(name, "name");
this.requestMarshaller = Preconditions.CheckNotNull(requestMarshaller, "requestMarshaller");
this.responseMarshaller = Preconditions.CheckNotNull(responseMarshaller, "responseMarshaller");
this.fullName = GetFullName(serviceName);
this.fullName = GetFullName(serviceName, name);
}
/// <summary>
/// Gets the type of the method.
/// </summary>
public MethodType Type
{
get
@ -77,6 +95,9 @@ namespace Grpc.Core
}
}
/// <summary>
/// Gets the name of the service to which this method belongs.
/// </summary>
public string ServiceName
{
get
@ -85,6 +106,9 @@ namespace Grpc.Core
}
}
/// <summary>
/// Gets the unqualified name of the method.
/// </summary>
public string Name
{
get
@ -93,6 +117,9 @@ namespace Grpc.Core
}
}
/// <summary>
/// Gets the marshaller used for request messages.
/// </summary>
public Marshaller<TRequest> RequestMarshaller
{
get
@ -101,6 +128,9 @@ namespace Grpc.Core
}
}
/// <summary>
/// Gets the marshaller used for response messages.
/// </summary>
public Marshaller<TResponse> ResponseMarshaller
{
get
@ -108,7 +138,11 @@ namespace Grpc.Core
return this.responseMarshaller;
}
}
/// <summary>
/// Gets the fully qualified name of the method. On the server side, methods are dispatched
/// based on this name.
/// </summary>
public string FullName
{
get
@ -120,9 +154,9 @@ namespace Grpc.Core
/// <summary>
/// Gets full name of the method including the service name.
/// </summary>
internal string GetFullName(string serviceName)
internal static string GetFullName(string serviceName, string methodName)
{
return "/" + Preconditions.CheckNotNull(serviceName, "serviceName") + "/" + this.Name;
return "/" + serviceName + "/" + methodName;
}
}
}

@ -36,22 +36,34 @@ using System;
namespace Grpc.Core
{
/// <summary>
/// Thrown when remote procedure call fails.
/// Thrown when remote procedure call fails. Every <c>RpcException</c> is associated with a resulting <see cref="Status"/> of the call.
/// </summary>
public class RpcException : Exception
{
private readonly Status status;
/// <summary>
/// Creates a new <c>RpcException</c> associated with given status.
/// </summary>
/// <param name="status">Resulting status of a call.</param>
public RpcException(Status status) : base(status.ToString())
{
this.status = status;
}
/// <summary>
/// Creates a new <c>RpcException</c> associated with given status and message.
/// </summary>
/// <param name="status">Resulting status of a call.</param>
/// <param name="message">The exception message.</param>
public RpcException(Status status, string message) : base(message)
{
this.status = status;
}
/// <summary>
/// Resulting status of the call.
/// </summary>
public Status Status
{
get

@ -31,12 +31,8 @@
#endregion
using System;
using System.Threading;
using System.Threading.Tasks;
using Grpc.Core.Internal;
namespace Grpc.Core
{
/// <summary>

@ -79,7 +79,7 @@ namespace Grpc.Core
where TRequest : class
where TResponse : class
{
callHandlers.Add(method.GetFullName(serviceName), ServerCalls.UnaryCall(method, handler));
callHandlers.Add(method.FullName, ServerCalls.UnaryCall(method, handler));
return this;
}
@ -89,7 +89,7 @@ namespace Grpc.Core
where TRequest : class
where TResponse : class
{
callHandlers.Add(method.GetFullName(serviceName), ServerCalls.ClientStreamingCall(method, handler));
callHandlers.Add(method.FullName, ServerCalls.ClientStreamingCall(method, handler));
return this;
}
@ -99,7 +99,7 @@ namespace Grpc.Core
where TRequest : class
where TResponse : class
{
callHandlers.Add(method.GetFullName(serviceName), ServerCalls.ServerStreamingCall(method, handler));
callHandlers.Add(method.FullName, ServerCalls.ServerStreamingCall(method, handler));
return this;
}
@ -109,7 +109,7 @@ namespace Grpc.Core
where TRequest : class
where TResponse : class
{
callHandlers.Add(method.GetFullName(serviceName), ServerCalls.DuplexStreamingCall(method, handler));
callHandlers.Add(method.FullName, ServerCalls.DuplexStreamingCall(method, handler));
return this;
}

@ -29,13 +29,12 @@
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
#endregion
using System;
using System.Runtime.InteropServices;
using Grpc.Core.Utils;
namespace Grpc.Core
{
/// <summary>
/// Represents RPC result.
/// Represents RPC result, which consists of <see cref="StatusCode"/> and an optional detail string.
/// </summary>
public struct Status
{
@ -52,6 +51,11 @@ namespace Grpc.Core
readonly StatusCode statusCode;
readonly string detail;
/// <summary>
/// Creates a new instance of <c>Status</c>.
/// </summary>
/// <param name="statusCode">Status code.</param>
/// <param name="detail">Detail.</param>
public Status(StatusCode statusCode, string detail)
{
this.statusCode = statusCode;
@ -80,6 +84,9 @@ namespace Grpc.Core
}
}
/// <summary>
/// Returns a <see cref="System.String"/> that represents the current <see cref="Grpc.Core.Status"/>.
/// </summary>
public override string ToString()
{
return string.Format("Status(StatusCode={0}, Detail=\"{1}\")", statusCode, detail);

@ -31,8 +31,6 @@
#endregion
using System;
namespace Grpc.Core
{
/// <summary>
@ -41,101 +39,101 @@ namespace Grpc.Core
/// </summary>
public enum StatusCode
{
/* Not an error; returned on success */
/// <summary>Not an error; returned on success.</summary>
OK = 0,
/* The operation was cancelled (typically by the caller). */
/// <summary>The operation was cancelled (typically by the caller).</summary>
Cancelled = 1,
/* Unknown error. An example of where this error may be returned is
if a Status value received from another address space belongs to
an error-space that is not known in this address space. Also
errors raised by APIs that do not return enough error information
may be converted to this error. */
/// <summary>
/// Unknown error. An example of where this error may be returned is
/// if a Status value received from another address space belongs to
/// an error-space that is not known in this address space. Also
/// errors raised by APIs that do not return enough error information
/// may be converted to this error.
/// </summary>
Unknown = 2,
/* Client specified an invalid argument. Note that this differs
from FAILED_PRECONDITION. INVALID_ARGUMENT indicates arguments
that are problematic regardless of the state of the system
(e.g., a malformed file name). */
/// <summary>
/// Client specified an invalid argument. Note that this differs
/// from FAILED_PRECONDITION. INVALID_ARGUMENT indicates arguments
/// that are problematic regardless of the state of the system
/// (e.g., a malformed file name).
/// </summary>
InvalidArgument = 3,
/* Deadline expired before operation could complete. For operations
that change the state of the system, this error may be returned
even if the operation has completed successfully. For example, a
successful response from a server could have been delayed long
enough for the deadline to expire. */
/// <summary>
/// Deadline expired before operation could complete. For operations
/// that change the state of the system, this error may be returned
/// even if the operation has completed successfully. For example, a
/// successful response from a server could have been delayed long
/// enough for the deadline to expire.
/// </summary>
DeadlineExceeded = 4,
/* Some requested entity (e.g., file or directory) was not found. */
/// <summary>Some requested entity (e.g., file or directory) was not found.</summary>
NotFound = 5,
/* Some entity that we attempted to create (e.g., file or directory)
already exists. */
/// <summary>Some entity that we attempted to create (e.g., file or directory) already exists.</summary>
AlreadyExists = 6,
/* The caller does not have permission to execute the specified
operation. PERMISSION_DENIED must not be used for rejections
caused by exhausting some resource (use RESOURCE_EXHAUSTED
instead for those errors). PERMISSION_DENIED must not be
used if the caller can not be identified (use UNAUTHENTICATED
instead for those errors). */
/// <summary>
/// The caller does not have permission to execute the specified
/// operation. PERMISSION_DENIED must not be used for rejections
/// caused by exhausting some resource (use RESOURCE_EXHAUSTED
/// instead for those errors). PERMISSION_DENIED must not be
/// used if the caller can not be identified (use UNAUTHENTICATED
/// instead for those errors).
/// </summary>
PermissionDenied = 7,
/* The request does not have valid authentication credentials for the
operation. */
/// <summary>The request does not have valid authentication credentials for the operation.</summary>
Unauthenticated = 16,
/* Some resource has been exhausted, perhaps a per-user quota, or
perhaps the entire file system is out of space. */
/// <summary>
/// Some resource has been exhausted, perhaps a per-user quota, or
/// perhaps the entire file system is out of space.
/// </summary>
ResourceExhausted = 8,
/* Operation was rejected because the system is not in a state
required for the operation's execution. For example, directory
to be deleted may be non-empty, an rmdir operation is applied to
a non-directory, etc.
A litmus test that may help a service implementor in deciding
between FAILED_PRECONDITION, ABORTED, and UNAVAILABLE:
(a) Use UNAVAILABLE if the client can retry just the failing call.
(b) Use ABORTED if the client should retry at a higher-level
(e.g., restarting a read-modify-write sequence).
(c) Use FAILED_PRECONDITION if the client should not retry until
the system state has been explicitly fixed. E.g., if an "rmdir"
fails because the directory is non-empty, FAILED_PRECONDITION
should be returned since the client should not retry unless
they have first fixed up the directory by deleting files from it.
(d) Use FAILED_PRECONDITION if the client performs conditional
REST Get/Update/Delete on a resource and the resource on the
server does not match the condition. E.g., conflicting
read-modify-write on the same resource. */
/// <summary>
/// Operation was rejected because the system is not in a state
/// required for the operation's execution. For example, directory
/// to be deleted may be non-empty, an rmdir operation is applied to
/// a non-directory, etc.
/// </summary>
FailedPrecondition = 9,
/* The operation was aborted, typically due to a concurrency issue
like sequencer check failures, transaction aborts, etc.
See litmus test above for deciding between FAILED_PRECONDITION,
ABORTED, and UNAVAILABLE. */
/// <summary>
/// The operation was aborted, typically due to a concurrency issue
/// like sequencer check failures, transaction aborts, etc.
/// </summary>
Aborted = 10,
/* Operation was attempted past the valid range. E.g., seeking or
reading past end of file.
Unlike INVALID_ARGUMENT, this error indicates a problem that may
be fixed if the system state changes. For example, a 32-bit file
system will generate INVALID_ARGUMENT if asked to read at an
offset that is not in the range [0,2^32-1], but it will generate
OUT_OF_RANGE if asked to read from an offset past the current
file size.
There is a fair bit of overlap between FAILED_PRECONDITION and
OUT_OF_RANGE. We recommend using OUT_OF_RANGE (the more specific
error) when it applies so that callers who are iterating through
a space can easily look for an OUT_OF_RANGE error to detect when
they are done. */
/// <summary>
/// Operation was attempted past the valid range. E.g., seeking or
/// reading past end of file.
/// </summary>
OutOfRange = 11,
/* Operation is not implemented or not supported/enabled in this service. */
/// <summary>Operation is not implemented or not supported/enabled in this service.</summary>
Unimplemented = 12,
/* Internal errors. Means some invariants expected by underlying
system has been broken. If you see one of these errors,
something is very broken. */
/// <summary>
/// Internal errors. Means some invariants expected by underlying
/// system has been broken. If you see one of these errors,
/// something is very broken.
/// </summary>
Internal = 13,
/* The service is currently unavailable. This is a most likely a
transient condition and may be corrected by retrying with
a backoff.
See litmus test above for deciding between FAILED_PRECONDITION,
ABORTED, and UNAVAILABLE. */
/// <summary>
/// The service is currently unavailable. This is a most likely a
/// transient condition and may be corrected by retrying with
/// a backoff.
/// </summary>
Unavailable = 14,
/* Unrecoverable data loss or corruption. */
/// <summary>Unrecoverable data loss or corruption.</summary>
DataLoss = 15
}
}

@ -39,6 +39,9 @@ using System.Threading.Tasks;
namespace Grpc.Core.Utils
{
/// <summary>
/// Utility methods to run microbenchmarks.
/// </summary>
public static class BenchmarkUtil
{
/// <summary>

@ -1,5 +1,37 @@
#region Copyright notice and license
// Copyright 2015, Google Inc.
// All rights reserved.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are
// met:
//
// * Redistributions of source code must retain the above copyright
// notice, this list of conditions and the following disclaimer.
// * Redistributions in binary form must reproduce the above
// copyright notice, this list of conditions and the following disclaimer
// in the documentation and/or other materials provided with the
// distribution.
// * Neither the name of Google Inc. nor the names of its
// contributors may be used to endorse or promote products derived from
// this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
#endregion
using System.Reflection;
using System.Runtime.CompilerServices;
// The current version of gRPC C#.
[assembly: AssemblyVersion(Grpc.Core.VersionInfo.CurrentVersion + ".0")]

@ -1,8 +1,41 @@
using System.Reflection;
using System.Runtime.CompilerServices;
#region Copyright notice and license
// Copyright 2015, Google Inc.
// All rights reserved.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are
// met:
//
// * Redistributions of source code must retain the above copyright
// notice, this list of conditions and the following disclaimer.
// * Redistributions in binary form must reproduce the above
// copyright notice, this list of conditions and the following disclaimer
// in the documentation and/or other materials provided with the
// distribution.
// * Neither the name of Google Inc. nor the names of its
// contributors may be used to endorse or promote products derived from
// this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
#endregion
namespace Grpc.Core
{
/// <summary>
/// Provides info about current version of gRPC.
/// </summary>
public static class VersionInfo
{
/// <summary>

Loading…
Cancel
Save