fix: docs of com.google.cloud.Timestamp.parseTimestamp (#258)

* docs: update doc of parseTimestamp

* docs: update doc of parseTimestamp

* docs: update doc and test of parseTimestamp

Author: athakor

google-cloud-core/src/main/java/com/google/cloud/Timestamp.java

@@ -28,6 +28,7 @@
 import org.threeten.bp.ZoneOffset;
 import org.threeten.bp.format.DateTimeFormatter;
 import org.threeten.bp.format.DateTimeFormatterBuilder;
+import org.threeten.bp.format.DateTimeParseException;
 import org.threeten.bp.temporal.TemporalAccessor;
 
 /**
@@ -189,8 +190,13 @@ public com.google.protobuf.Timestamp toProto() {
   }
 
   /**
-   * Creates a Timestamp instance from the given string. String is in the RFC 3339 format without
-   * the timezone offset (always ends in "Z").
+   * Creates a Timestamp instance from the given string. Input string should be in the RFC 3339
+   * format, like '2020-12-01T10:15:30.000Z' or with the timezone offset, such as
+   * '2020-12-01T10:15:30+01:00'.
+   *
+   * @param timestamp string in the RFC 3339 format
+   * @return created Timestamp
+   * @throws DateTimeParseException if unable to parse
    */
   public static Timestamp parseTimestamp(String timestamp) {
     TemporalAccessor temporalAccessor = timestampParser.parse(timestamp);

google-cloud-core/src/test/java/com/google/cloud/TimestampTest.java

@@ -257,6 +257,18 @@ public void parseTimestampWithoutTimeZoneOffset() {
         .isEqualTo(Timestamp.ofTimeSecondsAndNanos(TEST_TIME_SECONDS, 0));
   }
 
+  @Test
+  public void parseTimestampWithTimeZoneOffset() {
+    assertThat(Timestamp.parseTimestamp("0001-01-01T00:00:00-00:00"))
+        .isEqualTo(Timestamp.MIN_VALUE);
+    assertThat(Timestamp.parseTimestamp("9999-12-31T23:59:59.999999999-00:00"))
+        .isEqualTo(Timestamp.MAX_VALUE);
+    assertThat(Timestamp.parseTimestamp("2020-12-06T19:21:12.123+05:30"))
+        .isEqualTo(Timestamp.ofTimeSecondsAndNanos(1607262672, 123000000));
+    assertThat(Timestamp.parseTimestamp("2020-07-10T14:03:00-07:00"))
+        .isEqualTo(Timestamp.ofTimeSecondsAndNanos(1594414980, 0));
+  }
+
   @Test
   public void fromProto() {
     com.google.protobuf.Timestamp proto =