From 1d15d95d97803882635c0595a61caa155fcf33c8 Mon Sep 17 00:00:00 2001 From: Andreas Schildbach Date: Tue, 27 Feb 2018 21:19:31 +0100 Subject: [PATCH] Some Javadoc changes related to addresses. --- .../main/java/org/bitcoinj/core/Address.java | 52 +++++++++++++------ .../bitcoinj/core/WrongNetworkException.java | 2 +- .../java/org/bitcoinj/params/Networks.java | 2 +- .../java/org/bitcoinj/uri/BitcoinURI.java | 2 +- 4 files changed, 40 insertions(+), 18 deletions(-) diff --git a/core/src/main/java/org/bitcoinj/core/Address.java b/core/src/main/java/org/bitcoinj/core/Address.java index 71e229c2..56bd3e93 100644 --- a/core/src/main/java/org/bitcoinj/core/Address.java +++ b/core/src/main/java/org/bitcoinj/core/Address.java @@ -72,11 +72,11 @@ public class Address extends VersionedChecksummedBytes { } /** - * Construct an {@link Address} that represents the given pubkey hash. The resulting address will be a P2PKH type of + * Construct a {@link Address} that represents the given pubkey hash. The resulting address will be a P2PKH type of * address. * * @param params - * the network this address is valid for + * network this address is valid for * @param hash160 * 20-byte pubkey hash * @return constructed address @@ -86,34 +86,58 @@ public class Address extends VersionedChecksummedBytes { } /** - * Returns an {@link Address} that represents the public part of the given {@link ECKey}. Note that an address is - * derived from a hash of the public key and is not the public key itself (which is too large to be convenient). + * Construct a {@link Address} that represents the public part of the given {@link ECKey}. Note that an address is + * derived from a hash of the public key and is not the public key itself. + * + * @param params + * network this address is valid for + * @param key + * only the public part is used + * @return constructed address */ public static Address fromKey(NetworkParameters params, ECKey key) { return fromPubKeyHash(params, key.getPubKeyHash()); } - /** Returns an Address that represents the given P2SH script hash. */ + /** + * Construct a {@link Address} that represents the given P2SH script hash. + * + * @param params + * network this address is valid for + * @param hash160 + * P2SH script hash + * @return constructed address + */ public static Address fromP2SHHash(NetworkParameters params, byte[] hash160) { try { return new Address(params, params.getP2SHHeader(), hash160); } catch (WrongNetworkException e) { - throw new RuntimeException(e); // Cannot happen. + throw new RuntimeException(e); // Cannot happen. } } - /** Returns an Address that represents the script hash extracted from the given scriptPubKey */ + /** + * Constructs a {@link Address} that represents the script hash extracted from the given scriptPubKey. + * + * @param params + * network this address is valid for + * @param scriptPubKey + * scriptPubKey + * @return constructed address + */ public static Address fromP2SHScript(NetworkParameters params, Script scriptPubKey) { checkArgument(ScriptPattern.isPayToScriptHash(scriptPubKey), "Not a P2SH script"); return fromP2SHHash(params, ScriptPattern.extractHashFromPayToScriptHash(scriptPubKey)); } /** - * Construct an address from its Base58 representation. + * Construct a {@link Address} from its base58 form. + * * @param params - * The expected NetworkParameters or null if you don't want validation. + * expected network this address is valid for, or null if if the network should be derived from the + * base58 * @param base58 - * The textual form of the address, such as "17kzeh4N8g49GFvdDzSf8PjaPfyoD1MndL". + * base58-encoded textual form of the address * @throws AddressFormatException * if the given base58 doesn't parse or the checksum is invalid * @throws WrongNetworkException @@ -173,7 +197,7 @@ public class Address extends VersionedChecksummedBytes { * compatible with the current wallet. You should be able to handle a null response from this method. Note that the * parameters returned is not necessarily the same as the one the Address was created with. * - * @return a NetworkParameters representing the network the address is intended for. + * @return network the address is valid for */ public NetworkParameters getParameters() { return params; @@ -183,7 +207,8 @@ public class Address extends VersionedChecksummedBytes { * Given an address, examines the version byte and attempts to find a matching NetworkParameters. If you aren't sure * which network the address is intended for (eg, it was provided by a user), you can use this to decide if it is * compatible with the current wallet. - * @return a NetworkParameters of the address + * + * @return network the address is valid for * @throws AddressFormatException if the string wasn't of a known version */ public static NetworkParameters getParametersFromAddress(String address) throws AddressFormatException { @@ -205,9 +230,6 @@ public class Address extends VersionedChecksummedBytes { return false; } - /** - * This implementation narrows the return type to Address. - */ @Override public Address clone() throws CloneNotSupportedException { return (Address) super.clone(); diff --git a/core/src/main/java/org/bitcoinj/core/WrongNetworkException.java b/core/src/main/java/org/bitcoinj/core/WrongNetworkException.java index 3a545cac..a875ba4f 100644 --- a/core/src/main/java/org/bitcoinj/core/WrongNetworkException.java +++ b/core/src/main/java/org/bitcoinj/core/WrongNetworkException.java @@ -17,7 +17,7 @@ package org.bitcoinj.core; /** - * This exception is thrown by the Address class when you try and decode an address with a version code that isn't + * This exception is thrown by the address class when you try and decode an address with a version code that isn't * used by that network. You shouldn't allow the user to proceed in this case as they are trying to send money across * different chains, an operation that is guaranteed to destroy the money. */ diff --git a/core/src/main/java/org/bitcoinj/params/Networks.java b/core/src/main/java/org/bitcoinj/params/Networks.java index 03082ad0..6c2dc007 100644 --- a/core/src/main/java/org/bitcoinj/params/Networks.java +++ b/core/src/main/java/org/bitcoinj/params/Networks.java @@ -24,7 +24,7 @@ import java.util.Collection; import java.util.Set; /** - * Utility class that holds all the registered NetworkParameters types used for Address auto discovery. + * Utility class that holds all the registered NetworkParameters types used for address auto discovery. * By default only MainNetParams and TestNet3Params are used. If you want to use TestNet2, RegTestParams or * UnitTestParams use the register and unregister the TestNet3Params as they don't have their own address * version/type code. diff --git a/core/src/main/java/org/bitcoinj/uri/BitcoinURI.java b/core/src/main/java/org/bitcoinj/uri/BitcoinURI.java index 6b2f7eea..5bd52f90 100644 --- a/core/src/main/java/org/bitcoinj/uri/BitcoinURI.java +++ b/core/src/main/java/org/bitcoinj/uri/BitcoinURI.java @@ -255,7 +255,7 @@ public class BitcoinURI { } /** - * The Bitcoin Address from the URI, if one was present. It's possible to have Bitcoin URI's with no address if a + * The Bitcoin address from the URI, if one was present. It's possible to have Bitcoin URI's with no address if a * r= payment protocol parameter is specified, though this form is not recommended as older wallets can't understand * it. */