Minor javadoc changes, cleanup post #84

Author: cowtowncoder

release-notes/VERSION

@@ -8,6 +8,9 @@ Releases
 
 #78: TimeBasedEpochGenerator (UUIDv7) can't be provided a `UUIDClock`
  (reported by @Frozenlock)
+#84: Add `construct()` methods to specify the milliseconds being used
+  for time-based UUID generation
+ (contributed by @BranchPredictor)
 
 4.2.0 (14-May-2023)
 

src/main/java/com/fasterxml/uuid/impl/TimeBasedEpochGenerator.java

@@ -105,9 +105,18 @@ public UUID generate()
     }
 
     /**
-     * @since 4.3
+     * Method that will construct actual {@link UUID} instance for given
+     * unix epoch timestamp: called by {@link #generate()} but may alternatively be
+     * called directly to construct an instance with known timestamp.
+     * NOTE: calling this method directly produces somewhat distinct UUIDs as
+     * "entropy" value is still generated as necessary to avoid producing same
+     * {@link UUID} even if same timestamp is being passed.
+     *
      * @param rawTimestamp unix epoch millis
+     *
      * @return unix epoch time based UUID
+     *
+     * @since 4.3
      */
     public UUID construct(long rawTimestamp)
     {

src/main/java/com/fasterxml/uuid/impl/TimeBasedGenerator.java

@@ -89,14 +89,22 @@ public TimeBasedGenerator(EthernetAddress ethAddr, UUIDTimer timer)
     @Override
     public UUID generate()
     {
-        final long rawTimestamp = _timer.getTimestamp();
-        return construct(rawTimestamp);
+        return construct(_timer.getTimestamp());
     }
 
     /**
+     * Method that will construct actual {@link UUID} instance for given
+     * timestamp: called by {@link #generate()} but may alternatively be
+     * called directly to construct an instance with known timestamp.
+     * NOTE: calling this method directly does NOT guarantee uniqueness of resulting
+     * {@link UUID} (caller has to guarantee uniqueness)
+     *
+     * @param rawTimestamp Timestamp usually obtained from {@link UUIDTimer#getTimestamp()},
+     *   used for constructing UUID instance
+     *
+     * @return unix Time-based UUID constructed for given timestamp
+     *
      * @since 4.3
-     * @param rawTimestamp unix epoch millis
-     * @return unix epoch time based UUID
      */
     public UUID construct(long rawTimestamp)
     {

src/main/java/com/fasterxml/uuid/impl/TimeBasedReorderedGenerator.java

@@ -95,14 +95,22 @@ public TimeBasedReorderedGenerator(EthernetAddress ethAddr, UUIDTimer timer)
     public UUID generate()
     {
         // Ok, get 60-bit timestamp (4 MSB are ignored)
-        final long rawTimestamp = _timer.getTimestamp();
-        return construct(rawTimestamp);
+        return construct(_timer.getTimestamp());
     }
 
     /**
+     * Method that will construct actual {@link UUID} instance for given
+     * timestamp: called by {@link #generate()} but may alternatively be
+     * called directly to construct an instance with known timestamp.
+     * NOTE: calling this method directly does NOT guarantee uniqueness of resulting
+     * {@link UUID} (caller has to guarantee uniqueness)
+     *
+     * @param rawTimestamp Timestamp usually obtained from {@link UUIDTimer#getTimestamp()},
+     *   used for constructing UUID instance
+     *
+     * @return unix Time-based, Reordered UUID constructed for given timestamp
+     *
      * @since 4.3
-     * @param rawTimestamp unix epoch millis
-     * @return unix epoch time based UUID
      */
     public UUID construct(long rawTimestamp)
     {