Script, ScriptBuilder: clarify concept of creation time in the JavaDocs

core/src/main/java/org/bitcoinj/script/Script.java

@@ -226,8 +226,12 @@ public enum VerifyFlag {
     // must preserve the exact bytes that we read off the wire, along with the parsed form.
     @Nullable private final byte[] program;
 
-    // Creation time of the associated keys, or null if unknown.
-    @Nullable private final Instant creationTime;
+    /**
+     * If this is set, the script is associated with a creation time. This is currently used in the context of
+     * watching wallets only, where the scriptPubKeys being watched actually represent public keys and their addresses.
+     */
+    @Nullable
+    private final Instant creationTime;
 
     /**
      * Wraps given script chunks.
@@ -243,7 +247,7 @@ public static Script of(List<ScriptChunk> chunks) {
      * Wraps given script chunks.
      *
      * @param chunks       chunks to wrap
-     * @param creationTime creation time of the script
+     * @param creationTime creation time to associate the script with
      * @return script that wraps the chunks
      */
     public static Script of(List<ScriptChunk> chunks, Instant creationTime) {
@@ -263,12 +267,11 @@ public static Script parse(byte[] program) throws ScriptException {
     }
 
     /**
-     * Construct a script that copies and wraps a given program, and a creation time. The array is parsed and checked
-     * for syntactic validity. Programs like this are e.g. used in {@link TransactionInput} and
-     * {@link TransactionOutput}.
+     * Construct a script that copies and wraps a given program. The array is parsed and checked for syntactic
+     * validity. Programs like this are e.g. used in {@link TransactionInput} and {@link TransactionOutput}.
      *
      * @param program      Array of program bytes from a transaction.
-     * @param creationTime creation time of the script
+     * @param creationTime creation time to associate the script with
      * @return parsed program
      * @throws ScriptException if the program could not be parsed
      */
@@ -410,8 +413,11 @@ public List<ScriptChunk> getChunks() {
     }
 
     /**
-     * Gets the creation time of this script, or empty if unknown.
-     * @return creation time of this script, or empty if unknown
+     * Gets the associated creation time of this script, or empty if undefined. This is currently used in the context of
+     * watching wallets only, where the scriptPubKeys being watched actually represent public keys and their
+     * addresses.
+     *
+     * @return associated creation time of this script, or empty if undefined
      */
     public Optional<Instant> creationTime() {
         return Optional.ofNullable(creationTime);

core/src/main/java/org/bitcoinj/script/ScriptBuilder.java

@@ -61,6 +61,12 @@
  */
 public class ScriptBuilder {
     private final List<ScriptChunk> chunks;
+    /**
+     * If this is set, the script to be built is associated with a creation time. This is currently used in the
+     * context of watching wallets only, where the scriptPubKeys being watched actually represent public keys and
+     * their addresses.
+     */
+    @Nullable
     private Instant creationTime = TimeUtils.currentTime();
 
     /** Creates a fresh ScriptBuilder with an empty program. */
@@ -74,9 +80,12 @@ public ScriptBuilder(Script template) {
     }
 
     /**
-     * Sets the creation time to build the script with. If this is not set, the current time is used by the builder.
+     * Associates this script to be built with a given creation time. This is currently used in the context of
+     * watching wallets only, where the scriptPubKeys being watched actually represent public keys and their addresses.
+     * <p>
+     * If this is not set, the current time is used by the builder.
      *
-     * @param creationTime creation time to build the script with
+     * @param creationTime creation time to associate the script with
      * @return this builder
      */
     public ScriptBuilder creationTime(Instant creationTime) {