From fea737b39bde1a66a82b3e90b3ba7b3659e40d37 Mon Sep 17 00:00:00 2001
From: Sean Gilligan <sean@msgilligan.com>
Date: Mon, 2 Oct 2023 09:59:00 -0700
Subject: [PATCH] Address, AddressParser: improve JavaDoc regarding network
 normalization

---
 core/src/main/java/org/bitcoinj/base/Address.java |  9 +++++++--
 .../java/org/bitcoinj/base/AddressParser.java     | 15 ++++++++-------
 2 files changed, 15 insertions(+), 9 deletions(-)

diff --git a/core/src/main/java/org/bitcoinj/base/Address.java b/core/src/main/java/org/bitcoinj/base/Address.java
index 948b017fb..2a6451c97 100644
--- a/core/src/main/java/org/bitcoinj/base/Address.java
+++ b/core/src/main/java/org/bitcoinj/base/Address.java
@@ -107,8 +107,13 @@ public interface Address extends Comparable<Address> {
     int compareTo(Address o);
 
     /**
-     * Get the network this address works on. Use of {@link BitcoinNetwork} is preferred to use of {@link NetworkParameters}
-     * when you need to know what network an address is for.
+     * Get the network this address is used on. Returns the <i>normalized</i> network (see below.)
+     * <p>
+     * <b>Note:</b> The network value returned is <i>normalized</i>. For example the address {@code "tb1qw508d6qejxtdg4y5r3zarvary0c5xw7kxpjzsx"}
+     * may be used on either {@link BitcoinNetwork#TESTNET} or {@link BitcoinNetwork#SIGNET}, but the value returned by
+     * this method will always be {@link BitcoinNetwork#TESTNET}. Similarly, the address {@code "mnHUcqUVvrfi5kAaXJDQzBb9HsWs78b42R"}
+     * may be used on {@link BitcoinNetwork#TESTNET}, {@link BitcoinNetwork#REGTEST}, or {@link BitcoinNetwork#REGTEST}, but
+     * the value returned by this method will always be {@link BitcoinNetwork#TESTNET}.
      * @return the Network.
      */
     Network network();
diff --git a/core/src/main/java/org/bitcoinj/base/AddressParser.java b/core/src/main/java/org/bitcoinj/base/AddressParser.java
index 72c4a247d..7e460d3a5 100644
--- a/core/src/main/java/org/bitcoinj/base/AddressParser.java
+++ b/core/src/main/java/org/bitcoinj/base/AddressParser.java
@@ -22,17 +22,18 @@ import org.bitcoinj.core.NetworkParameters;
 import javax.annotation.Nullable;
 
 /**
- * Functional interface for address parsing. It takes a single parameter, but its behavior is context-specific. For example if the
- * function was created with ({@link AddressParser#getDefault(Network)} it will only parse addresses for a single expected
- * value of {@link Network}. Or, if created with {@link AddressParser#getDefault()} it will parse addresses matching any
- * network. The default set of known networks is defined by {@link BitcoinNetwork}, but be aware that the {@link Address#network()} value
- * is normalized (see {@link Address} for details.
+ * Functional interface for parsing an {@link Address}. It takes a {@link String} parameter and will parse address
+ * strings for a configured set of {@link Network}s. For example, if the parser was created with ({@link AddressParser#getDefault(Network)}
+ * it will only parse addresses for the provided value of {@link Network}. If created with {@link AddressParser#getDefault()} it will parse
+ * addresses matching any known network. The default set of known networks is defined by {@link BitcoinNetwork}.
+ * <p>
+ * Note: Be aware that the value returned by {@link Address#network()} will be normalized. See {@link Address#network()} for details.
  */
 @FunctionalInterface
 public interface AddressParser {
     /**
-     * Parse an address for any known/configured network
-     * @param addressString string representation of address
+     * Parse an address for a configured set of {@link Network}s.
+     * @param addressString string representation of an address
      * @return A validated address object
      * @throws AddressFormatException invalid address string
      */