duration.proto in grpc-tools-1.4.0

- old
+ new

@@ -45,10 +45,12 @@
 // resolution. It is independent of any calendar and concepts like "day"
 // or "month". It is related to Timestamp in that the difference between
 // two Timestamp values is a Duration and it can be added or subtracted
 // from a Timestamp. Range is approximately +-10,000 years.
 //
+// # Examples
+//
 // Example 1: Compute Duration from two Timestamps in pseudo code.
 //
 //     Timestamp start = ...;
 //     Timestamp end = ...;
 //     Duration duration = ...;
@@ -85,14 +87,25 @@
 //
 //     td = datetime.timedelta(days=3, minutes=10)
 //     duration = Duration()
 //     duration.FromTimedelta(td)
 //
+// # JSON Mapping
 //
+// In JSON format, the Duration type is encoded as a string rather than an
+// object, where the string ends in the suffix "s" (indicating seconds) and
+// is preceded by the number of seconds, with nanoseconds expressed as
+// fractional seconds. For example, 3 seconds with 0 nanoseconds should be
+// encoded in JSON format as "3s", while 3 seconds and 1 nanosecond should
+// be expressed in JSON format as "3.000000001s", and 3 seconds and 1
+// microsecond should be expressed in JSON format as "3.000001s".
+//
+//
 message Duration {
 
   // Signed seconds of the span of time. Must be from -315,576,000,000
-  // to +315,576,000,000 inclusive.
+  // to +315,576,000,000 inclusive. Note: these bounds are computed from:
+  // 60 sec/min * 60 min/hr * 24 hr/day * 365.25 days/year * 10000 years
   int64 seconds = 1;
 
   // Signed fractions of a second at nanosecond resolution of the span
   // of time. Durations less than one second are represented with a 0
   // `seconds` field and a positive or negative `nanos` field. For durations