Skip to content

Commit d6ac6b9

Browse files
JamesNKJamesNK
authored
Add XML docs to method provider APIs (#289)
1 parent 072a616 commit d6ac6b9

File tree

3 files changed

+76
-62
lines changed

3 files changed

+76
-62
lines changed

‎src/Grpc.AspNetCore.Server/Model/IServiceMethodProvider.cs‎

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -19,14 +19,21 @@
1919
namespace Grpc.AspNetCore.Server.Model
2020
{
2121
/// <summary>
22-
///
22+
/// Defines a contract for specifying methods for <typeparamref name="TService"/>.
2323
/// </summary>
24+
/// <remarks>
25+
/// <para>
26+
/// On application initialization, gRPC invokes all registered instances of <see cref="IServiceMethodProvider{TService}"/> to
27+
/// perform method discovery.
28+
/// <see cref="IServiceMethodProvider{TService}"/> instances are invoked in the order they are registered.
29+
/// </para>
30+
/// </remarks>
2431
public interface IServiceMethodProvider<TService> where TService : class
2532
{
2633
/// <summary>
27-
///
34+
/// Called to execute the provider.
2835
/// </summary>
29-
/// <param name="context"></param>
36+
/// <param name="context">The <see cref="ServiceMethodProviderContext{TService}"/>.</param>
3037
void OnServiceMethodDiscovery(ServiceMethodProviderContext<TService> context);
3138
}
3239
}

‎src/Grpc.AspNetCore.Server/Model/ServerMethods.cs‎

Lines changed: 40 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -25,52 +25,58 @@ namespace Grpc.AspNetCore.Server.Model
2525
// Needed because methods are executed with a new service instance each request.
2626

2727
/// <summary>
28-
///
28+
/// Server-side handler for a unary call.
2929
/// </summary>
30-
/// <typeparam name="TService"></typeparam>
31-
/// <typeparam name="TRequest"></typeparam>
32-
/// <typeparam name="TResponse"></typeparam>
33-
/// <param name="service"></param>
34-
/// <param name="request"></param>
35-
/// <param name="serverCallContext"></param>
36-
/// <returns></returns>
30+
/// <typeparam name="TService">Service type for this method.</typeparam>
31+
/// <typeparam name="TRequest">Request message type for this method.</typeparam>
32+
/// <typeparam name="TResponse">Response message type for this method.</typeparam>
33+
/// <param name="service">The service instance.</param>
34+
/// <param name="request">The request message.</param>
35+
/// <param name="serverCallContext">The <see cref="ServerCallContext"/> for the call.</param>
36+
/// <returns>
37+
/// A task that represents the completion of the call. The <see cref="Task{TResult}.Result"/>
38+
/// property returns a <typeparamref name="TResponse"/> for the call response.
39+
/// </returns>
3740
public delegate Task<TResponse> UnaryServerMethod<TService, TRequest, TResponse>(TService service, TRequest request, ServerCallContext serverCallContext);
3841

3942
/// <summary>
40-
///
43+
/// Server-side handler for a client streaming call.
4144
/// </summary>
42-
/// <typeparam name="TService"></typeparam>
43-
/// <typeparam name="TRequest"></typeparam>
44-
/// <typeparam name="TResponse"></typeparam>
45-
/// <param name="service"></param>
46-
/// <param name="stream"></param>
47-
/// <param name="serverCallContext"></param>
48-
/// <returns></returns>
45+
/// <typeparam name="TService">Service type for this method.</typeparam>
46+
/// <typeparam name="TRequest">Request message type for this method.</typeparam>
47+
/// <typeparam name="TResponse">Response message type for this method.</typeparam>
48+
/// <param name="service">The service instance.</param>
49+
/// <param name="stream">A <see cref="IAsyncStreamReader{TRequest}"/> that is used to read a stream of request messages.</param>
50+
/// <param name="serverCallContext">The <see cref="ServerCallContext"/> for the call.</param>
51+
/// <returns>
52+
/// A task that represents the completion of the call. The <see cref="Task{TResult}.Result"/>
53+
/// property returns a <typeparamref name="TResponse"/> for the call response.
54+
/// </returns>
4955
public delegate Task<TResponse> ClientStreamingServerMethod<TService, TRequest, TResponse>(TService service, IAsyncStreamReader<TRequest> stream, ServerCallContext serverCallContext);
5056

5157
/// <summary>
52-
///
58+
/// Server-side handler for a server streaming call.
5359
/// </summary>
54-
/// <typeparam name="TService"></typeparam>
55-
/// <typeparam name="TRequest"></typeparam>
56-
/// <typeparam name="TResponse"></typeparam>
57-
/// <param name="service"></param>
58-
/// <param name="request"></param>
59-
/// <param name="stream"></param>
60-
/// <param name="serverCallContext"></param>
61-
/// <returns></returns>
60+
/// <typeparam name="TService">Service type for this method.</typeparam>
61+
/// <typeparam name="TRequest">Request message type for this method.</typeparam>
62+
/// <typeparam name="TResponse">Response message type for this method.</typeparam>
63+
/// <param name="service">The service instance.</param>
64+
/// <param name="request">The request message.</param>
65+
/// <param name="stream">A <see cref="IServerStreamWriter{TResponse}"/> that is used to write a stream of response messages.</param>
66+
/// <param name="serverCallContext">The <see cref="ServerCallContext"/> for the call.</param>
67+
/// <returns>A task that represents the completion of the call.</returns>
6268
public delegate Task ServerStreamingServerMethod<TService, TRequest, TResponse>(TService service, TRequest request, IServerStreamWriter<TResponse> stream, ServerCallContext serverCallContext);
6369

6470
/// <summary>
65-
///
71+
/// Server-side handler for a duplex streaming call.
6672
/// </summary>
67-
/// <typeparam name="TService"></typeparam>
68-
/// <typeparam name="TRequest"></typeparam>
69-
/// <typeparam name="TResponse"></typeparam>
70-
/// <param name="service"></param>
71-
/// <param name="input"></param>
72-
/// <param name="output"></param>
73-
/// <param name="serverCallContext"></param>
74-
/// <returns></returns>
73+
/// <typeparam name="TService">Service type for this method.</typeparam>
74+
/// <typeparam name="TRequest">Request message type for this method.</typeparam>
75+
/// <typeparam name="TResponse">Response message type for this method.</typeparam>
76+
/// <param name="service">The service instance.</param>
77+
/// <param name="input">A <see cref="IAsyncStreamReader{TRequest}"/> that is used to read a stream of request messages.</param>
78+
/// <param name="output">A <see cref="IServerStreamWriter{TResponse}"/> that is used to write a stream of response messages.</param>
79+
/// <param name="serverCallContext">The <see cref="ServerCallContext"/> for the call.</param>
80+
/// <returns>A task that represents the completion of the call.</returns>
7581
public delegate Task DuplexStreamingServerMethod<TService, TRequest, TResponse>(TService service, IAsyncStreamReader<TRequest> input, IServerStreamWriter<TResponse> output, ServerCallContext serverCallContext);
7682
}

‎src/Grpc.AspNetCore.Server/Model/ServiceMethodProviderContext.cs‎

Lines changed: 26 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -24,8 +24,9 @@
2424
namespace Grpc.AspNetCore.Server.Model
2525
{
2626
/// <summary>
27-
///
27+
/// A context for <see cref="IServiceMethodProvider{TService}"/>.
2828
/// </summary>
29+
/// <typeparam name="TService">Service type for the context.</typeparam>
2930
public class ServiceMethodProviderContext<TService> where TService : class
3031
{
3132
private readonly ServerCallHandlerFactory<TService> _serverCallHandlerFactory;
@@ -39,13 +40,13 @@ internal ServiceMethodProviderContext(ServerCallHandlerFactory<TService> serverC
3940
internal List<MethodModel> Methods { get; }
4041

4142
/// <summary>
42-
///
43+
/// Adds a unary method to a service.
4344
/// </summary>
44-
/// <typeparam name="TRequest"></typeparam>
45-
/// <typeparam name="TResponse"></typeparam>
46-
/// <param name="method"></param>
47-
/// <param name="metadata"></param>
48-
/// <param name="invoker"></param>
45+
/// <typeparam name="TRequest">Request message type for this method.</typeparam>
46+
/// <typeparam name="TResponse">Response message type for this method.</typeparam>
47+
/// <param name="method">The method description.</param>
48+
/// <param name="metadata">The method metadata. This metadata can be used by routing and middleware when invoking a gRPC method.</param>
49+
/// <param name="invoker">The method invoker that is executed when the method is called.</param>
4950
public void AddUnaryMethod<TRequest, TResponse>(Method<TRequest, TResponse> method, IList<object> metadata, UnaryServerMethod<TService, TRequest, TResponse> invoker)
5051
where TRequest : class
5152
where TResponse : class
@@ -57,13 +58,13 @@ public void AddUnaryMethod<TRequest, TResponse>(Method<TRequest, TResponse> meth
5758
}
5859

5960
/// <summary>
60-
///
61+
/// Adds a server streaming method to a service.
6162
/// </summary>
62-
/// <typeparam name="TRequest"></typeparam>
63-
/// <typeparam name="TResponse"></typeparam>
64-
/// <param name="method"></param>
65-
/// <param name="metadata"></param>
66-
/// <param name="invoker"></param>
63+
/// <typeparam name="TRequest">Request message type for this method.</typeparam>
64+
/// <typeparam name="TResponse">Response message type for this method.</typeparam>
65+
/// <param name="method">The method description.</param>
66+
/// <param name="metadata">The method metadata. This metadata can be used by routing and middleware when invoking a gRPC method.</param>
67+
/// <param name="invoker">The method invoker that is executed when the method is called.</param>
6768
public void AddServerStreamingMethod<TRequest, TResponse>(Method<TRequest, TResponse> method, List<object> metadata, ServerStreamingServerMethod<TService, TRequest, TResponse> invoker)
6869
where TRequest : class
6970
where TResponse : class
@@ -75,13 +76,13 @@ public void AddServerStreamingMethod<TRequest, TResponse>(Method<TRequest, TResp
7576
}
7677

7778
/// <summary>
78-
///
79+
/// Adds a client streaming method to a service.
7980
/// </summary>
80-
/// <typeparam name="TRequest"></typeparam>
81-
/// <typeparam name="TResponse"></typeparam>
82-
/// <param name="method"></param>
83-
/// <param name="metadata"></param>
84-
/// <param name="invoker"></param>
81+
/// <typeparam name="TRequest">Request message type for this method.</typeparam>
82+
/// <typeparam name="TResponse">Response message type for this method.</typeparam>
83+
/// <param name="method">The method description.</param>
84+
/// <param name="metadata">The method metadata. This metadata can be used by routing and middleware when invoking a gRPC method.</param>
85+
/// <param name="invoker">The method invoker that is executed when the method is called.</param>
8586
public void AddClientStreamingMethod<TRequest, TResponse>(Method<TRequest, TResponse> method, List<object> metadata, ClientStreamingServerMethod<TService, TRequest, TResponse> invoker)
8687
where TRequest : class
8788
where TResponse : class
@@ -93,13 +94,13 @@ public void AddClientStreamingMethod<TRequest, TResponse>(Method<TRequest, TResp
9394
}
9495

9596
/// <summary>
96-
///
97+
/// Adds a duplex streaming method to a service.
9798
/// </summary>
98-
/// <typeparam name="TRequest"></typeparam>
99-
/// <typeparam name="TResponse"></typeparam>
100-
/// <param name="method"></param>
101-
/// <param name="metadata"></param>
102-
/// <param name="invoker"></param>
99+
/// <typeparam name="TRequest">Request message type for this method.</typeparam>
100+
/// <typeparam name="TResponse">Response message type for this method.</typeparam>
101+
/// <param name="method">The method description.</param>
102+
/// <param name="metadata">The method metadata. This metadata can be used by routing and middleware when invoking a gRPC method.</param>
103+
/// <param name="invoker">The method invoker that is executed when the method is called.</param>
103104
public void AddDuplexStreamingMethod<TRequest, TResponse>(Method<TRequest, TResponse> method, List<object> metadata, DuplexStreamingServerMethod<TService, TRequest, TResponse> invoker)
104105
where TRequest : class
105106
where TResponse : class

0 commit comments

Comments
 (0)