From 279d627b1ecf954eb2c00e3cc43783da80d4c52f Mon Sep 17 00:00:00 2001
From: Kurt Alfred Kluever <kak@google.com>
Date: Wed, 2 Aug 2023 10:20:45 -0700
Subject: [PATCH] Improve javadocs of `Timestamps.now()`.

PiperOrigin-RevId: 553183786
---
 .../main/java/com/google/protobuf/util/Timestamps.java    | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/java/util/src/main/java/com/google/protobuf/util/Timestamps.java b/java/util/src/main/java/com/google/protobuf/util/Timestamps.java
index 3e43700f7e..a1f30a7849 100644
--- a/java/util/src/main/java/com/google/protobuf/util/Timestamps.java
+++ b/java/util/src/main/java/com/google/protobuf/util/Timestamps.java
@@ -327,7 +327,13 @@ public final class Timestamps {
     }
   }
 
-  /** Create a Timestamp using the best-available system clock. */
+  /**
+   * Create a {@link Timestamp} using the best-available (in terms of precision) system clock.
+   *
+   * <p><b>Note:</b> that while this API is convenient, it may harm the testability of your code, as
+   * you're unable to mock the current time. Instead, you may want to consider injecting a clock
+   * instance to read the current time.
+   */
   public static Timestamp now() {
     if (INSTANT_NOW != null) {
       try {