JavaDoc Improvements

Final 1.0.0

Author: GoodforGod

src/main/java/io/api/etherscan/core/IAccountApi.java

@@ -15,34 +15,81 @@
  */
 public interface IAccountApi {
 
-    /** Address ETH balance */
+    /**
+     * Address ETH balance
+     * @param address get balance for
+     * @return balance
+     * @throws ApiException parent exception class
+     */
     @NotNull Balance balance(String address) throws ApiException;
 
-    /** ERC20 token balance for address */
+    /**
+     * ERC20 token balance for address
+     * @param address get balance for
+     * @param contract token contract
+     * @return token balance for address
+     * @throws ApiException parent exception class
+     */
     @NotNull TokenBalance balance(String address, String contract) throws ApiException;
 
     /**
      * Maximum 20 address for single batch request
-     * If address > 20, then there will be more than 1 request performed
+     * If address MORE THAN 20, then there will be more than 1 request performed
+     * @param addresses addresses to get balances for
+     * @return list of balances
+     * @throws ApiException parent exception class
      */
     @NotNull List<Balance> balances(List<String> addresses) throws ApiException;
 
-    /** All txs */
-    @NotNull List<Tx> txs(String address) throws ApiException;
-    @NotNull List<Tx> txs(String address, long startBlock) throws ApiException;
+    /**
+     * All txs for given address
+     * @param address get txs for
+     * @param startBlock tx from this blockNumber
+     * @param endBlock tx to this blockNumber
+     * @return txs for address
+     * @throws ApiException parent exception class
+     */
     @NotNull List<Tx> txs(String address, long startBlock, long endBlock) throws ApiException;
+    @NotNull List<Tx> txs(String address, long startBlock) throws ApiException;
+    @NotNull List<Tx> txs(String address) throws ApiException;
 
-    /** All internal txs */
-    @NotNull List<TxInternal> txsInternal(String address) throws ApiException;
-    @NotNull List<TxInternal> txsInternal(String address, long startBlock) throws ApiException;
+    /**
+     * All internal txs for given address
+     * @param address get txs for
+     * @param startBlock tx from this blockNumber
+     * @param endBlock tx to this blockNumber
+     * @return txs for address
+     * @throws ApiException parent exception class
+     */
     @NotNull List<TxInternal> txsInternal(String address, long startBlock, long endBlock) throws ApiException;
-    @NotNull List<TxInternal> txsInternalByHash(String txhash);
+    @NotNull List<TxInternal> txsInternal(String address, long startBlock) throws ApiException;
+    @NotNull List<TxInternal> txsInternal(String address) throws ApiException;
 
-    /** All token txs */
-    @NotNull List<TxToken> txsToken(String address) throws ApiException;
-    @NotNull List<TxToken> txsToken(String address, long startBlock) throws ApiException;
+    /**
+     * All internal tx for given transaction hash
+     * @param txhash transaction hash
+     * @return internal txs list
+     * @throws ApiException parent exception class
+     */
+    @NotNull List<TxInternal> txsInternalByHash(String txhash) throws ApiException;
+
+    /**
+     * All token txs for given address
+     * @param address get txs for
+     * @param startBlock tx from this blockNumber
+     * @param endBlock tx to this blockNumber
+     * @return txs for address
+     * @throws ApiException parent exception class
+     */
     @NotNull List<TxToken> txsToken(String address, long startBlock, long endBlock) throws ApiException;
+    @NotNull List<TxToken> txsToken(String address, long startBlock) throws ApiException;
+    @NotNull List<TxToken> txsToken(String address) throws ApiException;
 
-    /** All blocks mined by address */
+    /**
+     * All blocks mined by address
+     * @param address address to search for
+     * @return blocks mined
+     * @throws ApiException parent exception class
+     */
     @NotNull List<Block> minedBlocks(String address) throws ApiException;
 }

src/main/java/io/api/etherscan/core/IBlockApi.java

@@ -15,6 +15,11 @@
  */
 public interface IBlockApi {
 
-    /** Return uncle blocks */
+    /**
+     * Return uncle blocks
+     * @param blockNumber block number form 0 to last
+     * @return optional uncle blocks
+     * @throws ApiException parent exception class
+     */
     @NotNull Optional<UncleBlock> uncles(long blockNumber) throws ApiException;
 }

src/main/java/io/api/etherscan/core/IContractApi.java

@@ -13,6 +13,11 @@
  */
 public interface IContractApi {
 
-    /** Get Verified Contract Sources */
+    /**
+     * Get Verified Contract Sources
+     * @param address to verify
+     * @return ABI verified
+     * @throws ApiException parent exception class
+     */
     @NotNull Abi contractAbi(String address) throws ApiException;
 }

src/main/java/io/api/etherscan/core/ILogsApi.java

@@ -19,6 +19,11 @@ public interface ILogsApi {
     /**
      * alternative to the native eth_getLogs
      * Read at EtherScan API description for full info!
+     * @param query build log query
+     * @return logs according to query
+     * @throws ApiException parent exception class
+     *
+     * @see io.api.etherscan.model.query.impl.LogQueryBuilder
      */
     @NotNull List<Log> logs(LogQuery query) throws ApiException;
 }

src/main/java/io/api/etherscan/core/IProxyApi.java

@@ -21,87 +21,132 @@ public interface IProxyApi {
     /**
      * Returns the number of most recent block
      * eth_blockNumber
+     * @return last block number
+     * @throws ApiException parent exception class
      */
     long blockNoLast();
 
     /**
      * Returns information about a block by block number
      * eth_getBlockByNumber
+     * @param blockNo block number from 0 to last
+     * @return optional block result
+     * @throws ApiException parent exception class
      */
     @NotNull Optional<BlockProxy> block(long blockNo) throws ApiException;
 
     /**
      * Returns information about a uncle by block number
      * eth_getUncleByBlockNumberAndIndex
+     * @param blockNo block number from 0 to last
+     * @param index uncle block index
+     * @return optional block result
+     * @throws ApiException parent exception class
      */
     @NotNull Optional<BlockProxy> blockUncle(long blockNo, long index) throws ApiException;
 
     /**
      * Returns the information about a transaction requested by transaction hash
      * eth_getTransactionByHash
+     * @param txhash transaction hash
+     * @return optional tx result
+     * @throws ApiException parent exception class
      */
     @NotNull Optional<TxProxy> tx(String txhash) throws ApiException;
 
     /**
      * Returns information about a transaction by block number and transaction index position
      * eth_getTransactionByBlockNumberAndIndex
+     * @param blockNo block number from 0 to last
+     * @param index tx index in block
+     * @return optional tx result
+     * @throws ApiException parent exception class
      */
     @NotNull Optional<TxProxy> tx(long blockNo, long index) throws ApiException;
 
     /**
      * Returns the number of transactions in a block from a block matching the given block number
      * eth_getBlockTransactionCountByNumber
+     * @param blockNo block number from 0 to last
+     * @return transaction amount in block
+     * @throws ApiException parent exception class
      */
     int txCount(long blockNo) throws ApiException;
 
     /**
      * Returns the number of transactions sent from an address
      * eth_getTransactionCount
+     * @param address eth address
+     * @return transactions send amount from address
+     * @throws ApiException parent exception class
      */
     int txSendCount(String address) throws ApiException;
 
     /**
      * Creates new message call transaction or a contract creation for signed transactions
      * eth_sendRawTransaction
+     * @param hexEncodedTx encoded hex data to send
+     * @return optional string response
+     * @throws ApiException parent exception class
      */
     @NotNull Optional<String> txSendRaw(String hexEncodedTx) throws ApiException;
 
     /**
      * Returns the receipt of a transaction by transaction hash
      * eth_getTransactionReceipt
+     * @param txhash transaction hash
+     * @return optional tx receipt
+     * @throws ApiException parent exception class
      */
     @NotNull Optional<ReceiptProxy> txReceipt(String txhash) throws ApiException;
 
     /**
      * Executes a new message call immediately without creating a transaction on the block chain
      * eth_call
+     * @param address to call
+     * @param data data to call address
+     * @return optional the return value of executed contract.
+     * @throws ApiException parent exception class
      */
     @NotNull Optional<String> call(String address, String data) throws ApiException;
 
     /**
      * Returns code at a given address
      * eth_getCode
+     * @param address get code from
+     * @return optional the code from the given address
+     * @throws ApiException parent exception class
      */
     @NotNull Optional<String> code(String address) throws ApiException;
 
     /**
      * (**experimental)
      * Returns the value from a storage position at a given address
      * eth_getStorageAt
+     * @param address to get storage
+     * @param position storage position
+     * @return optional the value at this storage position
+     * @throws ApiException parent exception class
      */
     @NotNull Optional<String> storageAt(String address, long position) throws ApiException;
 
     /**
      * Returns the current price per gas in wei
      * eth_gasPrice
+     * @return estimated gas price
+     * @throws ApiException parent exception class
      */
     @NotNull BigInteger gasPrice() throws ApiException;
 
+
     /**
      * Makes a call or transaction, which won't be added to the blockchain and returns the used gas,
      * which can be used for estimating the used gas
      * eth_estimateGas
+     * @param hexData data to calc gas usage for
+     * @return estimated gas usage
+     * @throws ApiException parent exception class
      */
-    @NotNull BigInteger gasEstimated() throws ApiException;
     @NotNull BigInteger gasEstimated(String hexData) throws ApiException;
+    @NotNull BigInteger gasEstimated() throws ApiException;
 }

src/main/java/io/api/etherscan/core/IStatisticApi.java

@@ -16,12 +16,25 @@
  */
 public interface IStatisticApi {
 
-    /** ERC20 token total Supply */
+    /**
+     * ERC20 token total Supply
+     * @param contract contract address
+     * @return token supply for specified contract
+     * @throws ApiException parent exception class
+     */
     @NotNull BigInteger supply(String contract) throws ApiException;
 
-    /** Eth total supply */
+    /**
+     * Eth total supply
+     * @return total ETH supply for moment
+     * @throws ApiException parent exception class
+     */
     @NotNull Supply supply() throws ApiException;
 
-    /** Eth last USD and BTC price */
+    /**
+     * Eth last USD and BTC price
+     * @return last usd/btc price for ETH
+     * @throws ApiException parent exception class
+     */
     @NotNull Price lastPrice() throws ApiException;
 }

src/main/java/io/api/etherscan/core/ITransactionApi.java

@@ -15,12 +15,19 @@
  */
 public interface ITransactionApi {
 
-    /** Check Contract Execution Status (if there was an error during contract execution) */
+    /**
+     * Check Contract Execution Status (if there was an error during contract execution)
+     * @param txhash transaction hash
+     * @return optional status result
+     * @throws ApiException parent exception class
+     */
     @NotNull Optional<Status> execStatus(String txhash) throws ApiException;
 
-    /** Check Transaction Receipt Status (Only applicable for Post Byzantium fork transactions)
-     * 0 = Fail, 1 = Pass
-     * empty value for pre-byzantium fork
-     * */
+    /**
+     * Check Transaction Receipt Status (Only applicable for Post Byzantium fork transactions)
+     * @param txhash transaction hash
+     * @return 0 = Fail, 1 = Pass, empty value for pre-byzantium fork
+     * @throws ApiException parent exception class
+     */
     @NotNull Optional<Boolean> receiptStatus(String txhash) throws ApiException;
 }

src/main/java/io/api/etherscan/core/impl/EtherScanApi.java

@@ -82,48 +82,55 @@ public EtherScanApi(final String apiKey,
 
     /**
      * API for interactions with account and address
+     * @return account api
      */
     public IAccountApi account() {
         return account;
     }
 
     /**
      * API for verifying contract ABI
+     * @return contract api
      */
     public IContractApi contract() {
         return contract;
     }
 
     /**
      * [BETA] API for interaction with tx statuses
+     * @return transactions api
      */
     public ITransactionApi txs() {
         return txs;
     }
 
     /**
      * [BETA] API for getting block rewards and uncles
+     * @return block api
      */
     public IBlockApi block() {
         return block;
     }
 
     /**
      * [BETA] API for interaction with eth_getLogs
+     * @return logs api
      */
     public ILogsApi logs() {
         return logs;
     }
 
     /**
      * API for interacting with geth/proxy etherscan
+     * @return proxy api
      */
     public IProxyApi proxy() {
         return proxy;
     }
 
     /**
      * API for eth price and supply statistic
+     * @return statistic api
      */
     public IStatisticApi stats() {
         return stats;

src/main/java/io/api/etherscan/manager/IQueueManager.java

@@ -12,6 +12,7 @@ public interface IQueueManager {
 
     /**
      * Waits in queue for chance to take turn
+     * @return can or can not rake turn
      */
     boolean takeTurn();
 }

src/test/java/io/api/manager/QueueManagerTest.java

@@ -46,6 +46,6 @@ public void queueManagerTimeout() {
         long start = System.currentTimeMillis();
         queueManager.takeTurn();
         long end = System.currentTimeMillis();
-        assertEquals(3, (end - start) / 1000);
+        assertEquals(3, Math.round((double)(end - start)/1000));
     }
 }