2 files changed, 18 insertions, 11 deletions
diff --git a/csharp/src/Google.Protobuf/WellKnownTypes/Any.cs b/csharp/src/Google.Protobuf/WellKnownTypes/Any.cs
index 5836dfff..378b61d4 100644
--- a/csharp/src/Google.Protobuf/WellKnownTypes/Any.cs
+++ b/csharp/src/Google.Protobuf/WellKnownTypes/Any.cs
@@ -158,17 +158,18 @@ namespace Google.Protobuf.WellKnownTypes {
     public const int TypeUrlFieldNumber = 1;
     private string typeUrl_ = "";
     /// <summary>
-    /// A URL/resource name whose content describes the type of the
-    /// serialized protocol buffer message.
+    /// A URL/resource name that uniquely identifies the type of the serialized
+    /// protocol buffer message. The last segment of the URL's path must represent
+    /// the fully qualified name of the type (as in
+    /// `path/google.protobuf.Duration`). The name should be in a canonical form
+    /// (e.g., leading "." is not accepted).
     ///
-    /// For URLs which use the scheme `http`, `https`, or no scheme, the
-    /// following restrictions and interpretations apply:
+    /// In practice, teams usually precompile into the binary all types that they
+    /// expect it to use in the context of Any. However, for URLs which use the
+    /// scheme `http`, `https`, or no scheme, one can optionally set up a type
+    /// server that maps type URLs to message definitions as follows:
     ///
     /// * If no scheme is provided, `https` is assumed.
-    /// * The last segment of the URL's path must represent the fully
-    ///   qualified name of the type (as in `path/google.protobuf.Duration`).
-    ///   The name should be in a canonical form (e.g., leading "." is
-    ///   not accepted).
     /// * An HTTP GET on the URL must yield a [google.protobuf.Type][]
     ///   value in binary format, or produce an error.
     /// * Applications are allowed to cache lookup results based on the
@@ -177,6 +178,10 @@ namespace Google.Protobuf.WellKnownTypes {
     ///   on changes to types. (Use versioned type names to manage
     ///   breaking changes.)
     ///
+    /// Note: this functionality is not currently available in the official
+    /// protobuf release, and it is not used for type URLs beginning with
+    /// type.googleapis.com.
+    ///
     /// Schemes other than `http`, `https` (or the empty scheme) might be
     /// used with implementation specific semantics.
     /// </summary>
diff --git a/csharp/src/Google.Protobuf/WellKnownTypes/Timestamp.cs b/csharp/src/Google.Protobuf/WellKnownTypes/Timestamp.cs
index bf2943df..ef752be7 100644
--- a/csharp/src/Google.Protobuf/WellKnownTypes/Timestamp.cs
+++ b/csharp/src/Google.Protobuf/WellKnownTypes/Timestamp.cs
@@ -103,7 +103,9 @@ namespace Google.Protobuf.WellKnownTypes {
   /// {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional
   /// seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution),
   /// are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone
-  /// is required, though only UTC (as indicated by "Z") is presently supported.
+  /// is required. A proto3 JSON serializer should always use UTC (as indicated by
+  /// "Z") when printing the Timestamp type and a proto3 JSON parser should be
+  /// able to accept both UTC and other timezones (as indicated by an offset).
   ///
   /// For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past
   /// 01:30 UTC on January 15, 2017.
@@ -114,8 +116,8 @@ namespace Google.Protobuf.WellKnownTypes {
   /// to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime)
   /// with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one
   /// can use the Joda Time's [`ISODateTimeFormat.dateTime()`](
-  /// http://www.joda.org/joda-time/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime--)
-  /// to obtain a formatter capable of generating timestamps in this format.
+  /// http://www.joda.org/joda-time/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime--
+  /// ) to obtain a formatter capable of generating timestamps in this format.
   /// </summary>
   public sealed partial class Timestamp : pb::IMessage<Timestamp> {
     private static readonly pb::MessageParser<Timestamp> _parser = new pb::MessageParser<Timestamp>(() => new Timestamp());