Add Javadoc for bisq.asset types

src/main/java/bisq/asset/AbstractAsset.java

@@ -20,6 +20,14 @@
 import static org.apache.commons.lang3.Validate.notBlank;
 import static org.apache.commons.lang3.Validate.notNull;
 
+/**
+ * Abstract base class for {@link Asset} implementations. Most implementations should not
+ * extend this class directly, but should rather extend {@link Coin}, {@link Token} or one
+ * of their subtypes.
+ *
+ * @author Chris Beams
+ * @since 0.7.0
+ */
 public abstract class AbstractAsset implements Asset {
 
     private final String name;

src/main/java/bisq/asset/AddressValidationResult.java

@@ -17,6 +17,14 @@
 
 package bisq.asset;
 
+/**
+ * Value object representing the result of validating an {@link Asset} address. Various
+ * factory methods are provided for typical use cases.
+ *
+ * @author Chris Beams
+ * @since 0.7.0
+ * @see Asset#validateAddress(String)
+ */
 public class AddressValidationResult {
 
     private static AddressValidationResult VALID_ADDRESS = new AddressValidationResult(true, "", "");

src/main/java/bisq/asset/AddressValidator.java

@@ -17,6 +17,12 @@
 
 package bisq.asset;
 
+/**
+ * An {@link Asset} address validation function.
+ *
+ * @author Chris Beams
+ * @since 0.7.0
+ */
 public interface AddressValidator {
 
     AddressValidationResult validate(String address);

src/main/java/bisq/asset/Asset.java

@@ -17,6 +17,25 @@
 
 package bisq.asset;
 
+/**
+ * Interface representing a given ("crypto") asset in its most abstract form, having a
+ * {@link #getName() name}, e.g. "Bitcoin", a {@link #getTickerSymbol() ticker symbol},
+ * e.g. "BTC", and an address validation function. Together, these properties represent
+ * the minimum information and functionality required to register and trade an asset on
+ * the Bisq network.
+ * <p>
+ * Implementations typically extend either the {@link Coin} or {@link Token} base
+ * classes, and must be registered in the {@code META-INF/services/bisq.asset.Asset} file
+ * in order to be available in the {@link AssetRegistry} at runtime.
+ *
+ * @author Chris Beams
+ * @since 0.7.0
+ * @see AbstractAsset
+ * @see Coin
+ * @see Token
+ * @see Erc20Token
+ * @see AssetRegistry
+ */
 public interface Asset {
 
     String getName();

src/main/java/bisq/asset/AssetRegistry.java

@@ -22,6 +22,14 @@
 import java.util.ServiceLoader;
 import java.util.stream.Stream;
 
+/**
+ * Provides {@link Stream}-based access to {@link Asset} implementations registered in
+ * the {@code META-INF/services/bisq.asset.Asset} provider-configuration file.
+ *
+ * @author Chris Beams
+ * @since 0.7.0
+ * @see ServiceLoader
+ */
 public class AssetRegistry {
 
     private static final List<Asset> registeredAssets = new ArrayList<>();

src/main/java/bisq/asset/Base58BitcoinAddressValidator.java

@@ -22,6 +22,13 @@
 import org.bitcoinj.core.NetworkParameters;
 import org.bitcoinj.params.MainNetParams;
 
+/**
+ * {@link AddressValidator} for Base58-encoded Bitcoin addresses.
+ *
+ * @author Chris Beams
+ * @since 0.7.0
+ * @see org.bitcoinj.core.Address#fromBase58(NetworkParameters, String)
+ */
 public class Base58BitcoinAddressValidator implements AddressValidator {
 
     private final NetworkParameters networkParameters;

src/main/java/bisq/asset/Coin.java

@@ -17,6 +17,23 @@
 
 package bisq.asset;
 
+/**
+ * Abstract base class for {@link Asset}s with their own dedicated blockchain, such as
+ * {@link bisq.asset.coins.Bitcoin} itself or one of its many derivatives, competitors and
+ * alternatives, often called "altcoins", such as {@link bisq.asset.coins.Litecoin},
+ * {@link bisq.asset.coins.Ether}, {@link bisq.asset.coins.Monero} and
+ * {@link bisq.asset.coins.Zcash}.
+ * <p>
+ * In addition to the usual {@code Asset} properties, a {@code Coin} maintains information
+ * about which {@link Network} it may be used on. By default, coins are constructed with
+ * the assumption they are for use on that coin's "main network", or "main blockchain",
+ * i.e. that they are "real" coins for use in a production environment. In testing
+ * scenarios, however, a coin may be constructed for use only on "testnet" or "regtest"
+ * networks.
+ *
+ * @author Chris Beams
+ * @since 0.7.0
+ */
 public abstract class Coin extends AbstractAsset {
 
     public enum Network { MAINNET, TESTNET, REGTEST }

src/main/java/bisq/asset/DefaultAddressValidator.java

@@ -17,6 +17,17 @@
 
 package bisq.asset;
 
+/**
+ * {@link AddressValidator} for use when no more specific address validation function is
+ * available. This implementation only checks that a given address is non-null and
+ * non-empty; it exists for legacy purposes and is deprecated to indicate that new
+ * {@link Asset} implementations should NOT use it, but should rather provide their own
+ * {@link AddressValidator} implementation.
+ *
+ * @author Chris Beams
+ * @author Bernard Labno
+ * @since 0.7.0
+ */
 @Deprecated
 public class DefaultAddressValidator implements AddressValidator {
 

src/main/java/bisq/asset/Erc20Token.java

@@ -17,6 +17,14 @@
 
 package bisq.asset;
 
+/**
+ * Abstract base class for Ethereum-based {@link Token}s that implement the
+ * <a href="https://theethereum.wiki/w/index.php/ERC20_Token_Standard">ERC-20 Token
+ * Standard</a>.
+ *
+ * @author Chris Beams
+ * @since 0.7.0
+ */
 public abstract class Erc20Token extends Token {
 
     public Erc20Token(String name, String tickerSymbol) {

src/main/java/bisq/asset/EtherAddressValidator.java

@@ -17,10 +17,20 @@
 
 package bisq.asset;
 
+/**
+ * Validates an Ethereum address using the regular expression on record in the
+ * <a href="https://github.com/ethereum/web3.js/blob/bd6a890/lib/utils/utils.js#L405">
+ * ethereum/web3.js</a> project. Note that this implementation is widely used, not just
+ * for actual {@link bisq.asset.coins.Ether} address validation, but also for
+ * {@link Erc20Token} implementations and other Ethereum-based {@link Asset}
+ * implementations.
+ *
+ * @author Chris Beams
+ * @since 0.7.0
+ */
 public class EtherAddressValidator extends RegexAddressValidator {
 
     public EtherAddressValidator() {
-        // https://github.com/ethereum/web3.js/blob/master/lib/utils/utils.js#L403
         super("^(0x)?[0-9a-fA-F]{40}$");
     }
 }

src/main/java/bisq/asset/NetworkParametersAdapter.java

@@ -24,9 +24,16 @@
 import org.bitcoinj.core.StoredBlock;
 import org.bitcoinj.core.VerificationException;
 import org.bitcoinj.store.BlockStore;
-import org.bitcoinj.store.BlockStoreException;
 import org.bitcoinj.utils.MonetaryFormat;
 
+/**
+ * Convenient abstract {@link NetworkParameters} base class providing no-op
+ * implementations of all methods that are not required for address validation
+ * purposes.
+ *
+ * @author Chris Beams
+ * @since 0.7.0
+ */
 public abstract class NetworkParametersAdapter extends NetworkParameters {
 
     @Override
@@ -36,7 +43,7 @@ public String getPaymentProtocolId() {
 
     @Override
     public void checkDifficultyTransitions(StoredBlock storedPrev, Block next, BlockStore blockStore)
-            throws VerificationException, BlockStoreException {
+            throws VerificationException {
     }
 
     @Override

src/main/java/bisq/asset/RegexAddressValidator.java

@@ -17,6 +17,12 @@
 
 package bisq.asset;
 
+/**
+ * Validates an {@link Asset} address against a given regular expression.
+ *
+ * @author Chris Beams
+ * @since 0.7.0
+ */
 public class RegexAddressValidator implements AddressValidator {
 
     private final String regex;

src/main/java/bisq/asset/Token.java

@@ -17,6 +17,18 @@
 
 package bisq.asset;
 
+/**
+ * Abstract base class for {@link Asset}s that do not have their own dedicated blockchain,
+ * but are rather based on or derived from another blockchain. Contrast with {@link Coin}.
+ * Note that this is essentially a "marker" base class in the sense that it (currently)
+ * exposes no additional information or functionality beyond that found in
+ * {@link AbstractAsset}, but it is nevertheless useful in distinguishing between major
+ * different {@code Asset} types.
+ *
+ * @author Chris Beams
+ * @since 0.7.0
+ * @see Erc20Token
+ */
 public abstract class Token extends AbstractAsset {
 
     public Token(String name, String tickerSymbol, AddressValidator addressValidator) {

src/main/java/bisq/asset/package-info.java

@@ -0,0 +1,37 @@
+/*
+ * This file is part of Bisq.
+ *
+ * Bisq is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or (at
+ * your option) any later version.
+ *
+ * Bisq is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public
+ * License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Bisq. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+/**
+ * Bisq's family of abstractions representing different ("crypto")
+ * {@link bisq.asset.Asset} types such as {@link bisq.asset.Coin},
+ * {@link bisq.asset.Token} and {@link bisq.asset.Erc20Token}, as well as concrete
+ * implementations of each, such as {@link bisq.asset.coins.Bitcoin} itself, altcoins like
+ * {@link bisq.asset.coins.Litecoin} and {@link bisq.asset.coins.Ether} and tokens like
+ * {@link bisq.asset.tokens.DaiStablecoin}.
+ * <p>
+ * The purpose of this package is to provide everything necessary for registering
+ * ("listing") new assets and managing / accessing those assets within, e.g. the Bisq
+ * Desktop UI.
+ * <p>
+ * Note that everything within this package is intentionally designed to be simple and
+ * low-level with no dependencies on any other Bisq packages or components.
+ *
+ * @author Chris Beams
+ * @since 0.7.0
+ */
+
+package bisq.asset;

src/test/java/bisq/asset/AbstractAssetTest.java

@@ -26,6 +26,23 @@
 import static org.hamcrest.CoreMatchers.is;
 import static org.junit.Assert.assertThat;
 
+/**
+ * Abstract base class for all {@link Asset} unit tests. Subclasses must implement the
+ * {@link #testValidAddresses()} and {@link #testInvalidAddresses()} methods, and are
+ * expected to use the convenient {@link #assertValidAddress(String)} and
+ * {@link #assertInvalidAddress(String)} assertions when doing so.
+ * <p>
+ * Blank / empty addresses are tested automatically by this base class and are always
+ * considered invalid.
+ * <p>
+ * This base class also serves as a kind of integration test for {@link AssetRegistry}, in
+ * that all assets tested through subclasses are tested to make sure they are also
+ * properly registered and available there.
+ *
+ * @author Chris Beams
+ * @author Bernard Labno
+ * @since 0.7.0
+ */
 public abstract class AbstractAssetTest {
 
     private final AssetRegistry assetRegistry = new AssetRegistry();

src/test/java/bisq/asset/AbstractAssetWithDefaultValidatorTest.java

@@ -19,6 +19,15 @@
 
 import org.junit.Test;
 
+/**
+ * Convenient abstract base class for {@link Asset} implementations still using the
+ * deprecated {@link DefaultAddressValidator}.
+ *
+ * @author Bernard Labno
+ * @since 0.7.0
+ * @see DefaultAddressValidator
+ */
+@Deprecated
 public abstract class AbstractAssetWithDefaultValidatorTest extends AbstractAssetTest {
 
     public AbstractAssetWithDefaultValidatorTest(Asset asset) {