Update documentation on google.api.Http to include a complete

sample code about how to define a typical REST API using the
proto annotation `google.api.http`.

google/api/http.proto

@@ -27,27 +27,100 @@ option java_package = "com.google.api";
 // mapping is typically specified as an `google.api.http` annotation, see
 // "google/api/annotations.proto" for details.
 //
-// The mapping consists of a mandatory field specifying a path template and an
+// 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. Example:
+// body. The field name for the path indicates the HTTP method. Here is an
+// example of a REST API defined using this feature.
 //
 // ```
-// package google.storage.v2;
+// package example.messaging.v1;
 //
 // import "google/api/annotations.proto";
+// import "google/protobuf/empty.proto";
 //
-// service Storage {
-//   rpc CreateObject(CreateObjectRequest) returns (Object) {
+// 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.
+//   }
+//
+//   // Standard Update method.
+//   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: "/v2/{bucket_name=buckets/*}/objects"
-//       body: "object"
+//       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 {
 // }
 // ```
 //
-// Here `bucket_name` and `object` bind to fields of the request message
-// `CreateObjectRequest`.
+// NOTE: the notation `{message_id}` binds to the field `message_id` in the
+// corresponding method's request message.
 //
 // The rules for mapping HTTP path, query parameters, and body fields
 // to the request message are as follows:
@@ -76,7 +149,8 @@ option java_package = "com.google.api";
 // `LITERAL` a constant.  A `Variable` can match an entire path as specified
 // again by a template; this nested template must not contain further variables.
 // If no template is given with a variable, it matches a single path component.
-// The notation `{var}` is henceforth equivalent to `{var=*}`.
+// The notation `{var}` is henceforth equivalent to `{var=*}`. NOTE: the field
+// paths in variables and in the `body` must not refer to repeated fields.
 //
 // Use CustomHttpPattern to specify any HTTP method that is not included in the
 // pattern field, such as HEAD, or "*" to leave the HTTP method unspecified for
@@ -109,7 +183,7 @@ message HttpRule {
 
   // The name of the request field whose value is mapped to the HTTP body, or
   // `*` for mapping all fields not captured by the path pattern to the HTTP
-  // body.
+  // body. NOTE: the referred field must not be a repeated field.
   string body = 7;
 
   // Additional HTTP bindings for the selector. Nested bindings must not