Merge pull request grpc#213 from jtattermusch/csharp_client_vs_stub

Fix confusion caused by terms "client" and "stub".

Author: LisaFC

docs/guides/concepts.md

@@ -66,9 +66,8 @@ We'll look at the different types of RPC in more detail in the RPC life cycle se
 
 Starting from a service definition in a .proto file, gRPC provides protocol buffer compiler plugins that generate client- and server-side code. gRPC users typically call these APIs on the client side and implement the corresponding API on the server side.
 
-- On the server side, the server implements the service interface and runs a gRPC server to handle client calls. The gRPC infrastructure decodes incoming requests, executes service methods, and encodes service responses.
-- On the client side, the client has a *stub* that implements exactly the same methods as the server. The client can then just call those methods on the local stub, wrapping the parameters in the appropriate protocol buffer message type — gRPC looks after sending the request(s) to the server and returning the server's protocol buffer response(s).
-
+- On the server side, the server implements the methods declared by the service and runs a gRPC server to handle client calls. The gRPC infrastructure decodes incoming requests, executes service methods, and encodes service responses.
+- On the client side, the client has a local object known as *stub* (for some languages, the preferred term is *client*) that implements the same methods as the service. The client can then just call those methods on the local object, wrapping the parameters for the call in the appropriate protocol buffer message type - gRPC looks after sending the request(s) to the server and returning the server's protocol buffer response(s).
 
 ### Synchronous vs. asynchronous
 
@@ -84,7 +83,7 @@ Now let's take a closer look at what happens when a gRPC client calls a gRPC ser
 
 First let's look at the simplest type of RPC, where the client sends a single request and gets back a single response.
 
-- Once the client calls the method on the stub, the server is notified that the RPC has been invoked with the client's [metadata](#metadata) for this call, the method name, and the specified [deadline](#deadlines) if applicable.
+- Once the client calls the method on the stub/client object, the server is notified that the RPC has been invoked with the client's [metadata](#metadata) for this call, the method name, and the specified [deadline](#deadlines) if applicable.
 - The server can then either send back its own initial metadata (which must be sent before any response) straight away, or wait for the client's request message - which happens first is application-specific.
 - Once the server has the client's request message, it does whatever work is necessary to create and populate its response. The response is then returned (if successful) to the client together with status details (status code and optional status message) and optional trailing metadata.
 - If the status is OK, the client then gets the response, which completes the call on the client side.
@@ -136,7 +135,7 @@ TBD
 
 ### Channels
 
-A gRPC channel provides a connection to a gRPC server on a specified host and port and is used when creating a client stub. Clients can specify channel arguments to modify gRPC's default behaviour, such as switching on and off message compression. A channel has state, including <code>connected</code> and <code>idle</code>.
+A gRPC channel provides a connection to a gRPC server on a specified host and port and is used when creating a client stub (or just "client" in some languages). Clients can specify channel arguments to modify gRPC's default behaviour, such as switching on and off message compression. A channel has state, including <code>connected</code> and <code>idle</code>.
 
 How gRPC deals with closing down channels is language-dependent. Some languages also permit querying channel state.
 

docs/index.md

@@ -42,7 +42,8 @@ services. As in many RPC systems, gRPC is based around the idea of defining
 a *service*, specifying the methods that can be called remotely with their
 parameters and return types. On the server side, the server implements this
 interface and runs a gRPC server to handle client calls. On the client side,
-the client has a *stub* that provides exactly the same methods as the server.
+the client has a *stub* (referred to as just *client* in some languages)
+that provides the same methods as the server.
 
 <img src="../img/grpc_concept_diagram_00.png" class="img-responsive" alt="gRPC diagram">
 
@@ -436,8 +437,8 @@ As you can see, a gRPC method can accept only a single protocol buffer message t
 Once we've defined our service, we use the protocol buffer compiler
 `protoc` to generate the special client and server code we need to create
 our application - you
-can generate gRPC code in any gRPC-supported language, although PHP and Objective-C only support creating clients. The generated code contains both stub code for clients to
-use and an abstract interface for servers to implement, both with the method
+can generate gRPC code in any gRPC-supported language, although PHP and Objective-C only support creating clients. The generated code contains both client-side code for clients to
+call into and an abstract interface for servers to implement, both with the method
 defined in our `Greeter` service.
 
 (If you didn't install the gRPC plugins and protoc on your system and are just reading along with
@@ -577,9 +578,8 @@ To generate the code, run the following command from the `examples/csharp/hellow
 
 Running the appropriate command for your OS regenerates the following files in the Greeter directory:
 
-- `Greeter/Helloworld.cs` defines a namespace `Helloworld`
-  - This contains all the protocol buffer code to populate, serialize, and retrieve our request and response message types
-- `Greeter/HelloworldGrpc.cs`, provides stub and service classes, including:
+- `Greeter/Helloworld.cs` contains all the protocol buffer code to populate, serialize, and retrieve our request and response message types
+- `Greeter/HelloworldGrpc.cs` provides generated client and server classes, including:
    - an abstract base class `Greeter.GreeterBase` to inherit from when defining RouteGuide service implementations
    - a class `Greeter.GreeterClient` that can be used to access remote RouteGuide instances
 
@@ -947,7 +947,7 @@ we'll leave that for the tutorial.
 
 First let's look at how we connect to the `Greeter` server. First we need
 to create a gRPC channel, specifying the hostname and port of the server we
-want to connect to. Then we use the channel to construct the stub instance.
+want to connect to. Then we use the channel to construct the client stub instance.
 
 
 <div class="tabs">
@@ -1077,7 +1077,7 @@ In PHP, we can do this in a single step using the `GreeterClient` class's constr
 Now we can contact the service and obtain a greeting:
 
 1. We construct and fill in a `HelloRequest` to send to the service.
-2. We call the stub's `SayHello()` RPC with our request and get a populated `HelloReply` if the RPC is successful, from which we can get our greeting.
+2. We call the client stub's `SayHello()` RPC with our request and get a populated `HelloReply` if the RPC is successful, from which we can get our greeting.
 
 <div class="tabs">
   <ul>

docs/tutorials/basic/csharp.md

@@ -52,7 +52,7 @@ service RouteGuide {
 
 Then you define `rpc` methods inside your service definition, specifying their request and response types. gRPC lets you define four kinds of service method, all of which are used in the `RouteGuide` service:
 
-- A *simple RPC* where the client sends a request to the server using the stub and waits for a response to come back, just like a normal function call.
+- A *simple RPC* where the client sends a request to the server using the client object and waits for a response to come back, just like a normal function call.
 
 ```protobuf
    // Obtains the feature at a given position.
@@ -123,9 +123,8 @@ To generate the code, the following command should be run from the `examples/csh
 
 Running the appropriate command for your OS regenerates the following files in the RouteGuide directory:
 
-- `RouteGuide/RouteGuide.cs` defines a namespace `Routeguide`
-  - This contains all the protocol buffer code to populate, serialize, and retrieve our request and response message types
-- `RouteGuide/RouteGuideGrpc.cs`, provides stub and service classes
+- `RouteGuide/RouteGuide.cs` contains all the protocol buffer code to populate, serialize, and retrieve our request and response message types
+- `RouteGuide/RouteGuideGrpc.cs` provides generated client and server classes, including:
    - an abstract class `RouteGuide.RouteGuideBase` to inherit from when defining RouteGuide service implementations
    - a class `RouteGuide.RouteGuideClient` that can be used to access remote RouteGuide instances
 
@@ -284,9 +283,9 @@ As you can see, we build and start our server using `Grpc.Core.Server` class. To
 
 In this section, we'll look at creating a C# client for our `RouteGuide` service. You can see our complete example client code in [examples/csharp/route_guide/RouteGuideClient/Program.cs](https://github.com/grpc/grpc/blob/{{ site.data.config.grpc_release_branch }}/examples/csharp/route_guide/RouteGuideClient/Program.cs).
 
-### Creating a stub
+### Creating a client object
 
-To call service methods, we first need to create a *stub*.
+To call service methods, we first need to create a client object (also referred to as *stub* for other gRPC languages).
 
 First, we need to create a gRPC client channel that will connect to gRPC server. Then, we create an instance of the `RouteGuite.RouteGuideClient` class generated from our .proto, passing the channel as an argument.