diff --git a/google/api/http.proto b/google/api/http.proto
index 0141667a..4bbadbb7 100644
--- a/google/api/http.proto
+++ b/google/api/http.proto
@@ -21,107 +21,150 @@ option java_outer_classname = "HttpProto";
 option java_package = "com.google.api";
 
 
-// `HttpRule` defines the mapping of an RPC method to one or more HTTP REST API
-// methods. The mapping determines what portions of the request message are
-// populated from the path, query parameters, or body of the HTTP request.  The
-// mapping is typically specified as an `google.api.http` annotation, see
-// "google/api/annotations.proto" for details.
+// `HttpRule` defines the mapping of an RPC method to one or more HTTP
+// REST APIs.  The mapping determines what portions of the request
+// message are populated from the path, query parameters, or body of
+// the HTTP request.  The mapping is typically specified as an
+// `google.api.http` annotation, see "google/api/annotations.proto"
+// for details.
 //
-// The mapping consists of a required field specifying a path template and an
-// optional `body` field specifying what data is represented in the HTTP request
-// body. The field name for the path indicates the HTTP method. Here is an
-// example of a REST API defined using this feature.
-//
-// ```
-// package example.messaging.v1;
-//
-// import "google/api/annotations.proto";
-// import "google/protobuf/empty.proto";
+// The mapping consists of a field specifying the path template and
+// method kind.  The path template can refer to fields in the request
+// message, as in the example below which describes a REST GET
+// operation on a resource collection of messages:
 //
+// ```proto
 // service Messaging {
-//   // Standard List method.
-//   rpc ListMessages(ListMessagesRequest) returns (ListMessagesResponse) {
-//     option (google.api.http).get = "/v1/messages";
-//     // No body for HTTP GET.
-//   }
-//
-//   // Standard Create method.
-//   rpc CreateMessage(CreateMessageRequest) returns (Message) {
-//     option (google.api.http) = {
-//       post: "/v1/messages"
-//       body: "message"
-//     };
-//   }
-//
-//   // Standard Get method.
 //   rpc GetMessage(GetMessageRequest) returns (Message) {
 //     option (google.api.http).get = "/v1/messages/{message_id}";
-//     // No body for HTTP GET.
 //   }
+// }
+// message GetMessageRequest {
+//   string message_id = 1; // mapped to the URL
+// }
+// message Message {
+//   string text = 1; // content of the resource
+// }
+// ```
 //
-//   // Standard Update method.
+// This definition enables an automatic, bidrectional mapping of HTTP
+// JSON to RPC. Example:
+//
+// HTTP | RPC
+// -----|-----
+// `GET /v1/messages/123456`  | `GetMessage(message_id: "123456")`
+//
+// In general, not only fields but also field paths can be referenced
+// from a path pattern. Fields mapped to the path pattern cannot be
+// repeated and must have a primitive (non-message) type.
+//
+// Any fields in the request message which are not bound by the path
+// pattern automatically become (optional) HTTP query
+// parameters. Assume the following definition of the request message:
+//
+// ```proto
+// message GetMessageRequest {
+//   string message_id = 1; // mapped to the URL
+//   int64 revision = 2;    // becomes a parameter
+// }
+// ```
+//
+// This enables a HTTP JSON to RPC mapping as below:
+//
+// HTTP | RPC
+// -----|-----
+// `GET /v1/messages/123456?revision=2` | `GetMessage(message_id: "123456" revision: 2)`
+//
+// Note that fields which are mapped to HTTP parameters must have a
+// primitive type or a repeated primitive type. Message types are not
+// allowed. In the case of a repeated type, the parameter can be
+// repeated in the URL, as in `...?param=A&param=B`.
+//
+// For HTTP method kinds which allow a request body, the `body` field
+// specifies the mapping. Consider a REST update method on the
+// message resource collection:
+//
+// ```proto
+// service Messaging {
 //   rpc UpdateMessage(UpdateMessageRequest) returns (Message) {
 //     option (google.api.http) = {
 //       put: "/v1/messages/{message_id}"
 //       body: "message"
-//     };
-//   }
-//   // Standard Delete method.
-//   rpc DeleteMessage(DeleteMessageRequest) returns (google.protobuf.Empty) {
-//     option (google.api.http).delete = "/v1/messages/{message_id}";
-//     // No body for HTTP DELETE.
-//   }
-//
-//   // A custom Forward method.
-//   rpc ForwardMessage(ForwardMessageRequest)
-//       returns (ForwardMessageResponse) {
-//     option (google.api.http) {
-//       post: "/v1/messages/{message_id}:forward"
-//       body: "*"
-//     };
 //   }
 // }
-//
-// message Message {
-//   string text = 1;
-// }
-//
-// message ListMessageRequest {
-// }
-//
-// message ListMesageResponse {
-//   repeated Message messages = 1;
-// }
-//
-// message CreateMessageRequest {
-//   Message message = 1;
-// }
-//
-// message GetMessageRequest {
-//   string message_id = 1;
-// }
-//
 // message UpdateMessageRequest {
-//   string message_id = 1;
-//   Message message = 2;
-// }
-//
-// message DeleteMessageRequest {
-//   string message_id = 1;
-// }
-//
-// message ForwardMessageRequest {
-//   string message_id = 1;
-//   string forward_address = 2;
-// }
-//
-// message ForwardMessageResponse {
+//   string message_id = 1; // mapped to the URL
+//   Message message = 2;   // mapped to the body
 // }
 // ```
 //
-// NOTE: the notation `{message_id}` binds to the field `message_id` in the
-// corresponding method's request message.
+// The following HTTP JSON to RPC mapping is enabled, where the
+// representation of the JSON in the request body is determined by
+// protos JSON encoding:
 //
+// HTTP | RPC
+// -----|-----
+// `PUT /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id: "123456" message { text: "Hi!" })`
+//
+// The special name `*` can be used in the body mapping to define that
+// every field not bound by the path template should be mapped to the
+// request body.  This enables the following alternative definition of
+// the update method:
+//
+// ```proto
+// service Messaging {
+//   rpc UpdateMessage(Message) returns (Message) {
+//     option (google.api.http) = {
+//       put: "/v1/messages/{message_id}"
+//       body: "*"
+//   }
+// }
+// message Message {
+//   string message_id = 2;
+//   string text = 2;
+// }
+// ```
+//
+// The following HTTP JSON to RPC mapping is enabled:
+//
+// HTTP | RPC
+// -----|-----
+// `PUT /v1/messages/123456 { "text": "Hi!" }` | `UpdateMessage(message_id: "123456" text: "Hi!")`
+//
+// Note that when using `*` in the body mapping, it is not possible to
+// have HTTP parameters, as all fields not bound by the path end in
+// the body. This makes this option more rarely used in practice of
+// defining REST APIs. The common usage of `*` is in custom methods
+// which don't use the URL at all for transferring data.
+//
+// It is possible to define multiple HTTP methods for one RPC by using
+// the `additional_bindings` option. Example:
+//
+// ```proto
+// service Messaging {
+//   rpc GetMessage(GetMessageRequest) returns (Message) {
+//     option (google.api.http) = {
+//       get: "/v1/messages/{message_id}"
+//       additional_bindings {
+//         get: "/v1/users/{user_id}/messages/{message_id}"
+//       }
+//   }
+// }
+// message GetMessageRequest {
+//   string message_id = 1;
+//   string user_id = 2;
+// }
+// ```
+//
+// This enables the following two alternative HTTP JSON to RPC
+// mappings:
+//
+// HTTP | RPC
+// -----|-----
+// `GET /v1/messages/123456` | `GetMessage(message_id: "123456")`
+// `GET /v1/users/me/messages/123456` | `GetMessage(user_id: "me" message_id: "123456")`
+//
+// # Rules for HTTP mapping
 // The rules for mapping HTTP path, query parameters, and body fields
 // to the request message are as follows:
 //
@@ -186,8 +229,9 @@ message HttpRule {
   // body. NOTE: the referred field must not be a repeated field.
   string body = 7;
 
-  // Additional HTTP bindings for the selector. Nested bindings must not
-  // specify a selector and must not contain additional bindings.
+  // Additional HTTP bindings for the selector. Nested bindings must
+  // not contain an `additional_bindings` field themselves (that is,
+  // the nesting may only be one level deep).
   repeated HttpRule additional_bindings = 11;
 }