Merge remote-tracking branch 'origin/master'

# Conflicts:
#	src/main/java/io/api/etherscan/core/IAccountApi.java
#	src/main/java/io/api/etherscan/core/IBlockApi.java
#	src/main/java/io/api/etherscan/core/IContractApi.java
#	src/main/java/io/api/etherscan/core/ILogsApi.java
#	src/main/java/io/api/etherscan/core/IProxyApi.java
#	src/main/java/io/api/etherscan/core/IStatisticApi.java
#	src/main/java/io/api/etherscan/core/ITransactionApi.java
#	src/main/java/io/api/etherscan/core/impl/EtherScanApi.java
#	src/main/java/io/api/etherscan/manager/IQueueManager.java
#	src/test/java/io/api/etherscan/logs/LogQueryBuilderTest.java
#	src/test/java/io/api/etherscan/proxy/ProxyTxApiTest.java
#	src/test/java/io/api/etherscan/proxy/ProxyTxReceiptApiTest.java
#	src/test/java/io/api/manager/QueueManagerTest.java
#	src/test/java/io/api/util/BasicUtilsTests.java

Author: GoodforGod

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

@@ -17,59 +17,79 @@ public interface IAccountApi {
 
     /**
      * Address ETH balance
-     * @param address to look for
+     * @param address get balance for
      * @return balance
+     * @throws ApiException parent exception class
      */
     @NotNull Balance balance(String address) throws ApiException;
 
     /**
      * ERC20 token balance for address
-     * @param address to look for
-     * @param contract for token
-     * @return  token balance
+     * @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 addresses more than 20, then there will be MORE than 1 request performed
-     * @param addresses to look for
-     * @return balance[0] for address[0], etc
+     * 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;
 
     /**
-     * Find all txs
-     * @param address to look for txs
-     * @return tx info
+     * 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) throws ApiException;
-    @NotNull List<Tx> txs(String address, long startBlock) throws ApiException;
     @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
-     * @param address to look for
-     * @return internal tx
+     * 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) throws ApiException;
-    @NotNull List<TxInternal> txsInternal(String address, long startBlock) throws ApiException;
     @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
-     * @param address to look for
-     * @return token txs
+     * 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) throws ApiException;
-    @NotNull List<TxToken> txsToken(String address, long startBlock) throws ApiException;
     @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
-     * @param address to look for
-     * @return mined blocks
+     * @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

@@ -17,8 +17,9 @@ public interface IBlockApi {
 
     /**
      * Return uncle blocks
-     * @param blockNumber block number
-     * @return uncle block
+     * @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

@@ -15,8 +15,9 @@ public interface IContractApi {
 
     /**
      * Get Verified Contract Sources
-     * @param address to look for
-     * @return abi for contract
+     * @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

@@ -17,11 +17,13 @@
 public interface ILogsApi {
 
     /**
-     * Alternative to the native eth_getLogs
+     * alternative to the native eth_getLogs
      * Read at EtherScan API description for full info!
-     * @see LogQuery
-     * @param query for logs (check etherscan specs)
-     * @return logs
+     * @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

@@ -22,115 +22,131 @@ 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
-     * @return block info
+     * @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
+     * @param blockNo block number from 0 to last
      * @param index uncle block index
-     * @return block info
+     * @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 tx hash
-     * @return tx info
+     * @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
+     * @param blockNo block number from 0 to last
      * @param index tx index in block
-     * @return tx info
+     * @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
-     * @return tx count in block
+     * @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 to look for
-     * @return tx send count
+     * @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 tx as hex
-     * @return result (check eth grpc info)
+     * @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 tx hash
-     * @return receipt
+     * @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 look for
-     * @param data in tx for call
-     * @return result (check eth grpc info)
+     * @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 to look for
-     * @return result (check eth grpc info)
+     * @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 look for
+     * @param address to get storage
      * @param position storage position
-     * @return result (check eth grpc info)
+     * @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 price
+     * @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
-     * @return gas estimate
+     * @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

@@ -18,20 +18,23 @@ public interface IStatisticApi {
 
     /**
      * ERC20 token total Supply
-     * @param contract to look for
-     * @return token 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
-     * @return ETH supply
+     * @return total ETH supply for moment
+     * @throws ApiException parent exception class
      */
     @NotNull Supply supply() throws ApiException;
 
     /**
      * Eth last USD and BTC price
-     * @return last 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

@@ -17,17 +17,17 @@ public interface ITransactionApi {
 
     /**
      * Check Contract Execution Status (if there was an error during contract execution)
-     * @param txhash to look for
-     * @return exec status
+     * @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
-     * @param txhash to look for
-     * @return status as boolean
+     * @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/ProxyApiProvider.java

@@ -143,7 +143,8 @@ public Optional<String> txSendRaw(final String hexEncodedTx) throws ApiException
         final StringProxyTO response = postRequest(urlParams, "", StringProxyTO.class);
         if(response.getError() != null)
             throw new EtherScanException("Error occurred with code " + response.getError().getCode()
-                    + " with message " + response.getError().getMessage());
+                    + " with message " + response.getError().getMessage()
+                    + ", error id " + response.getId() + ", jsonRPC " + response.getJsonrpc());
 
         return Optional.ofNullable(response.getResult());
     }

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

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