Update documentation for google.rpc.Code and google.rpc.Status.

Now `Status` contains the desription of the overall error model.

google/rpc/code.proto

@@ -21,14 +21,12 @@ option java_outer_classname = "CodeProto";
 option java_package = "com.google.rpc";
 
 
-// Error codes for One Platform APIs. They MUST match the canonical
-// error space for Google3 APIs.
-//
+// The canonical error codes for Google APIs.
 // Warnings:
-// (a) Do not change any numeric assignments.
-// (b) Changes to this list should only be made if there is a compelling
-//     need that cannot be satisfied in another way.  Such changes
-//     must be approved by at least two OWNERS.
+//
+// -   Do not change any numeric assignments.
+// -   Changes to this list should only be made if there is a compelling
+//     need that can't be satisfied in another way.
 //
 // Sometimes multiple error codes may apply.  Services should return
 // the most specific error code that applies.  For example, prefer

google/rpc/status.proto

@@ -23,14 +23,63 @@ option java_outer_classname = "StatusProto";
 option java_package = "com.google.rpc";
 
 
-// Represents the RPC error status for Google APIs.
+// The `Status` defines a logical error model that is suitable for different
+// programming environments, including REST APIs and RPC APIs. It is used by
+// [gRPC](https://github.com/grpc). The error model is designed to be:
+//
+// - Simple to use and understand for most users.
+// - Flexible enough to meet unexpected needs.
+//
+// # Overview
+// The `Status` message contains 3 pieces of data: error code, error message,
+// and error details. The error code should be an enum value of
+// [google.rpc.Code][google.rpc.Code], but it may accept additional error codes if needed.  The
+// error message should be a developer-facing English message that helps
+// developers *understand* and *resolve* the error. If a localized user-facing
+// error message is needed, it can be sent in the error details or localized by
+// the client. The optional error details may contain arbitrary information
+// about the error. There is a predefined set of error detail types in the
+// package `google.rpc` which can be used for common error conditions.
+//
+// # Language mapping
+// The `Status` message is the logical representation of the error model, but it
+// is not necessarily the actual wire format. When the `Status` message is
+// exposed in different client libraries and different wire protocols, it can be
+// mapped differently. For example, it will likely be mapped to some exceptions
+// in Java, but more likely mapped to some error codes in C.
+//
+// # Other uses
+// The error model and the `Status` message can be used in a variety of
+// environments - either with or without APIs - to provide consistent developer
+// experience across different environments.
+//
+// Example uses of this error model include:
+//
+// - Partial errors. If a service needs to return partial errors to the client,
+//     it may embed the `Status` in the normal response to indicate the partial
+//     errors.
+//
+// - Workflow errors. A typical workflow has multiple steps. Each step may
+//     have a `Status` message for error reporting purpose.
+//
+// - Batch operations. If a client uses batch request and batch response, the
+//     `Status` message should be used directly inside batch response, one for
+//     each error sub-response.
+//
+// - Asynchronous operations. If an API call embeds asynchronous operation
+//     results in its response, the status of those operations should be
+//     represented directly using the `Status` message.
+//
+// - Logging. If some API errors are stored in logs, the message `Status` could
+//     be used directly after any stripping needed for security/privacy reasons.
+//
 message Status {
   // The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
   int32 code = 1;
 
-  // A developer-facing error message, which should be in English.  The
-  // user-facing error message should be localized and stored in the
-  // [google.rpc.Status.details][google.rpc.Status.details] field.
+  // A developer-facing error message, which should be in English. Any
+  // user-facing error message should be localized and sent in the
+  // [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
   string message = 2;
 
   // A list of messages that carry the error details.  There will be a