From e11917e1b827da0131a8345e5c83bc3249cc816f Mon Sep 17 00:00:00 2001
From: Carl Mastrangelo <notcarl@google.com>
Date: Wed, 22 Jun 2016 18:07:29 -0700
Subject: [PATCH] core: add package level javadoc.

Fixes #714
---
 core/src/main/java/io/grpc/package-info.java | 38 +++++++++++++++++++-
 1 file changed, 37 insertions(+), 1 deletion(-)

diff --git a/core/src/main/java/io/grpc/package-info.java b/core/src/main/java/io/grpc/package-info.java
index cd37e20e7f..b03aa45ef5 100644
--- a/core/src/main/java/io/grpc/package-info.java
+++ b/core/src/main/java/io/grpc/package-info.java
@@ -29,7 +29,43 @@
  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
+package io.grpc;
 /**
  * The gRPC core public API.
+ *
+ * <p>gRPC is based on a client-server model of remote procedural calls.  A client creates a
+ * channel which is connected to a server.  RPCs are initiated from the client and sent to the
+ * server which then responds back to the client.  When the client and server are done sending
+ * messages, they half close their respective connections.  The RPC is complete as soon as the
+ * server closes.
+ *
+ * <p>To send an RPC, first create a {@link Channel} using {@link ManagedChannelBuilder#forTarget}.
+ * When using auto generate Protobuf stubs, the stub class will have constructors for wrapping the
+ * channel.  These include {@code newBlockingStub}, {@code newStub}, and {@code newFutureStub}
+ * which you can use based on your design.  The stub is the primary way a client interacts with a
+ * server.
+ *
+ * <p>To receive RPCs, create a {@link Server} using {@link ServerBuilder#forPort}.  The Protobuf
+ * stub will contain an abstract class called AbstractFoo, where Foo is the name of your service.
+ * Extend this class, and pass an instance of it to {@link ServerBuilder#addService}.  Once your
+ * server is built, call {@link Server#start} to begin accepting RPCs.
+ *
+ * <p>Both Clients and Servers should use a custom {@link java.util.concurrent.Executor}.  The gRPC
+ * runtime includes a default executor that eases testing and examples, but is not ideal for use in
+ * a production environment.  See the associated documentation in the respective builders.
+ *
+ * <p>Clients and Servers can also be gracefully shutdown gracefully using the {@code shutdown}
+ * method.  The API to conduct an orderly shutdown is modeled from the
+ * {@link java.util.concurrent.ExecutorService}.
+ *
+ * <p>gRPC also includes support for more advanced features, such as name resolution, load
+ * balancing, bidirectional streaming, health checking, and more.  See the relative methods in the
+ * client and server builders.
+ *
+ * <p>Development of gRPC is done primary on Github at
+ * <a href="https://github.com/grpc/grpc-java">https://github.com/grpc/grpc-java</a>, where the gRPC
+ * team welcomes contributions and bug reports.  There is also a mailing list at
+ * <a href="https://groups.google.com/forum/#!forum/grpc-io">grpc-io</a> if you have questions
+ * about gRPC.
  */
-package io.grpc;
+