Add more documentation for transports.

- Add package descriptions for transport, netty and okhttp.
- Describe transports (netty, okhttp and inprocess) in README

README.md

@@ -231,22 +231,30 @@ protoc=/path/to/protoc
 Navigating Around the Source
 ----------------------------
 
-Heres a quick readers guide to the code to help folks get started. At a high level there are three distinct layers
-to the library: stub, channel & transport.
+Heres a quick readers guide to the code to help folks get started. At a high
+level there are three distinct layers to the library: __Stub__, __Channel__ &
+__Transport__.
 
 ### Stub
 
-The 'stub'  layer is what is exposed to most developers and provides type-safe bindings to whatever 
-datamodel/IDL/interface you are adapting. An example is provided of a binding to code generated by the protocol-buffers compiler but others should be trivial to add and are welcome.
+The Stub layer is what is exposed to most developers and provides type-safe
+bindings to whatever datamodel/IDL/interface you are adapting. gRPC comes with
+a [plugin](https://github.com/google/grpc-java/blob/master/compiler) to the
+protocol-buffers compiler that generates Stub interfaces out of `.proto` files,
+but bindings to other datamodel/IDL should be trivial to add and are welcome.
 
 #### Key Interfaces
 
 [Stream Observer](https://github.com/google/grpc-java/blob/master/stub/src/main/java/io/grpc/stub/StreamObserver.java)
 
-
 ### Channel
 
-The 'channel' layer is an abstraction over transport handling that is suitable for interception/decoration and exposes more behavior to the application than the stub layer. It is intended to be easy for application frameworks to use this layer to address cross-cutting concerns such as logging, monitoring, auth etc. Flow-control is also exposed at this layer to allow more sophisticated applications to interact with it directly.
+The Channel layer is an abstraction over Transport handling that is suitable for
+interception/decoration and exposes more behavior to the application than the
+Stub layer. It is intended to be easy for application frameworks to use this
+layer to address cross-cutting concerns such as logging, monitoring, auth etc.
+Flow-control is also exposed at this layer to allow more sophisticated
+applications to interact with it directly.
 
 #### Common
 
@@ -265,7 +273,28 @@ The 'channel' layer is an abstraction over transport handling that is suitable f
 
 ### Transport
 
-The 'transport' layer does the heavy lifting of putting & taking bytes off the wire. The interfaces to it are abstract just enough to allow plugging in of different implementations. Transports are modeled as 'Stream' factories. The variation in interface between a server stream and a client stream exists to codify their differing semantics for cancellation and error reporting.
+The Transport layer does the heavy lifting of putting & taking bytes off the
+wire. The interfaces to it are abstract just enough to allow plugging in of
+different implementations. Transports are modeled as `Stream` factories. The
+variation in interface between a server Stream and a client Stream exists to
+codify their differing semantics for cancellation and error reporting.
+
+Note the transport layer API is considered internal to gRPC and has weaker API
+guarantees than the core API under package `io.grpc`.
+
+gRPC comes with tree Transport implementations:
+
+1. The [Netty-based](https://github.com/google/grpc-java/blob/master/netty)
+   transport is the main transport implementation based on
+   [Netty](http://netty.io). It is for both the client and the server.
+2. The [OkHttp-based](https://github.com/google/grpc-java/blob/master/okhttp)
+   transport is a lightweight transport based on
+   [OkHttp](http://square.github.io/okhttp/). It is mainly for use on Android
+   and is for clinet only.
+3. The
+   [inprocess](https://github.com/google/grpc-java/blob/master/core/src/main/java/io/grpc/transport/inprocess)
+   transport is for when a server is in the same process as the client. It is
+   useful for testing.
 
 #### Common
 
@@ -285,4 +314,6 @@ The 'transport' layer does the heavy lifting of putting & taking bytes off the w
 
 ### Examples
 
-Tests showing how these layers are composed to execute calls using protobuf messages can be found here https://github.com/google/grpc-java/tree/master/interop-testing/src/main/java/io/grpc/testing/integration
+Tests showing how these layers are composed to execute calls using protobuf
+messages can be found here
+https://github.com/google/grpc-java/tree/master/interop-testing/src/main/java/io/grpc/testing/integration

core/src/main/java/io/grpc/transport/package-info.java

@@ -0,0 +1,12 @@
+/**
+ * The transport layer that does the heavy lifting of putting and taking bytes off the wire.
+ *
+ * <p>Note the transport layer API is considered internal to gRPC and has weaker API guarantees than
+ * the core API under package {@code io.grpc}.
+ *
+ * <p>The interfaces to it are abstract just enough to allow plugging in of different
+ * implementations.  Transports are modeled as {@code Stream} factories. The variation in interface
+ * between a server stream and a client stream exists to codify their differing semantics for
+ * cancellation and error reporting.
+ */
+package io.grpc.transport;

netty/src/main/java/io/grpc/transport/netty/package-info.java

@@ -0,0 +1,5 @@
+/**
+ * The main transport implementation based on <a target="_blank" href="http://netty.io">Netty</a>,
+ * for both the client and the server.
+ */
+package io.grpc.transport.netty;

okhttp/src/main/java/io/grpc/transport/okhttp/package-info.java

@@ -0,0 +1,6 @@
+/**
+ * A lightweight transport based on
+ * <a target="_blank" href="http://square.github.io/okhttp/">OkHttp</a>, mainly for use on Android
+ * (client-only).
+ */
+package io.grpc.transport.okhttp;