Clean-up of the JavaDoc

io-hotmoka-node-local-api/src/main/java/io/hotmoka/node/local/api/ResponseBuilder.java

@@ -46,6 +46,11 @@ public interface ResponseBuilder<Request extends TransactionRequest<Response>, R
 	 */
 	ResponseCreation<Response> getResponseCreation() throws TransactionRejectedException, StoreException, InterruptedException;
 
+	/**
+	 * The result of the creation of a response.
+	 *
+	 * @param <Response> the type of the response
+	 */
 	interface ResponseCreation<Response extends TransactionResponse> {
 
 		/**

io-hotmoka-node-local/src/main/java/io/hotmoka/node/local/AbstractInitialResponseBuilder.java

@@ -53,9 +53,17 @@ protected abstract class ResponseCreator extends InitialResponseBuilderImpl<Requ
 
 		/**
 		 * Creates the response from the request.
+		 * 
+		 * @throws TransactionRejectedException if the request is rejected
+		 * @throws StoreException if the store of the node misbehaves
 		 */
 		protected ResponseCreator() throws TransactionRejectedException, StoreException {}
 
+		/**
+		 * Checks if the request should be rejected, even before trying to execute it.
+		 * 
+		 * @throws TransactionRejectedException if the request should be rejected
+		 */
 		protected void checkConsistency() throws TransactionRejectedException {
 			try {
 				if (environment.getManifest().isPresent())

io-hotmoka-node-local/src/main/java/io/hotmoka/node/local/AbstractNonInitialResponseBuilder.java

@@ -57,6 +57,9 @@ protected abstract class ResponseCreator extends NonInitialResponseBuilderImpl<R
 
 		/**
 		 * Creates the response from the request.
+		 * 
+		 * @throws TransactionRejectedException if the request is rejected
+		 * @throws StoreException if the store of the node misbehaves
 		 */
 		protected ResponseCreator() throws TransactionRejectedException, StoreException {}
 

io-hotmoka-node-local/src/main/java/io/hotmoka/node/local/AbstractTrieBasedStore.java

@@ -64,12 +64,9 @@ protected AbstractTrieBasedStore(AbstractTrieBasedStore<N,C,S,T> toClone, StoreC
 	 * Creates a clone of a store, up to cache and roots.
 	 * 
 	 * @param toClone the store to clone
+	 * @param stateId the state to check out in the cloned store
 	 * @param cache to caches to use in the cloned store
-	 * @param rootOfResponses the root to use for the tries of responses
-	 * @param rootOfInfo the root to use for the tries of info
-	 * @param rootOfHistories the root to use for the tries of histories
-	 * @param rootOfRequests the root to use for the tries of requests
-     * @throws UnknownStateIdException if the required state does not exist
+     * @throws UnknownStateIdException if {@code stateId} does not exist
      * @throws StoreException if the operation could not be completed correctly
 	 */
     protected AbstractTrieBasedStore(AbstractTrieBasedStore<N,C,S,T> toClone, StateId stateId, Optional<StoreCache> cache) throws UnknownStateIdException, StoreException {

io-hotmoka-node-local/src/main/java/io/hotmoka/node/local/LRUCache.java

@@ -26,16 +26,15 @@
  * wherein if the cache size has reached the maximum allocated capacity, the
  * least recently used objects in the cache will be evicted.
  * 
- * @author sunil
- *
- * @param <K>
- * @param <V>
- *
  * <p>
  *        Date: 14/Nov/2019
  * </p>
  * 
  * Taken from https://dzone.com/articles/java-based-simple-cache-lru-eviction.
+ * 
+ * @author sunil
+ * @param <K> the type of the keys of the cache
+ * @param <V> the type of the values of the cache
  */
 public final class LRUCache<K, V> {
 
@@ -44,8 +43,8 @@ public final class LRUCache<K, V> {
 	 * 
 	 * @author sunil
 	 *
-	 * @param <K>
-	 * @param <V>
+	 * @param <K> the type of the keys of the cache
+	 * @param <V> the type of the values of the cache
 	 */
 	private static class Node<K, V> {
 		private V value;
@@ -92,6 +91,12 @@ public String toString() {
 		this(16, maxCapacity);
 	}*/
 
+	/**
+	 * Creates an LRU cache with the given capacities.
+	 * 
+	 * @param initialCapacity the initial capacity of the cache
+	 * @param maxCapacity the maximal capacity of the cache
+	 */
 	public LRUCache(int initialCapacity, int maxCapacity) {
 		this.maxCapacity = maxCapacity;
 		this.map = new HashMap<>(Math.min(initialCapacity, maxCapacity));

io-hotmoka-node-mokamint/src/main/java/io/hotmoka/node/mokamint/MokamintNodes.java

@@ -38,29 +38,38 @@ private MokamintNodes() {}
 	 * Creates and starts a node with a brand new store, of a blockchain based on Mokamint.
 	 * It spawns the Mokamint engine with an application for handling its transactions.
 	 * 
-	 * @param config the configuration of the blockchain
+	 * @param config the configuration of the Hotmoka node
+	 * @param mokamintConfig the configuration of the underlying Mokamint node
+	 * @param keyPair the keys of the Mokamint node, used to sign the blocks that it mines
 	 * @param createGenesis if true, creates a genesis block and starts mining on top
-	 *                      (initial synchronization is consequently skipped)
+	 *                      (initial synchronization is consequently skipped), otherwise it waits
+	 *                      for whispered blocks and then starts mining on top of them
 	 * @return the Mokamint node
 	 * @throws InterruptedException if the current thread is interrupted before completing the operation
 	 * @throws NodeException if the operation cannot be completed correctly
 	 * @throws TimeoutException if some operation timed out
+	 * @throws InvalidKeyException if the {@code keyPair} is invalid
+	 * @throws SignatureException if the genesis block cannot be signed with {@code keyPair}
 	 */
 	public static MokamintNode init(MokamintNodeConfig config, LocalNodeConfig mokamintConfig, KeyPair keyPair, boolean createGenesis) throws NodeException, InterruptedException, InvalidKeyException, SignatureException, TimeoutException {
 		return new MokamintNodeImpl(config, mokamintConfig, keyPair, true, createGenesis);
 	}
 
 	/**
-	 * Starts a Mokamint node that uses an already existing store. The consensus
+	 * Creates and starts a Mokamint node that uses an already existing store. The consensus
 	 * parameters are recovered from the manifest in the store, hence the store must
 	 * be that of an already initialized blockchain. It spawns the Mokamint engine
 	 * and connects it to an application for handling its transactions.
 	 * 
-	 * @param config the configuration of the blockchain
+	 * @param config the configuration of the Hotmoka node
+	 * @param mokamintConfig the configuration of the underlying Mokamint node
+	 * @param keyPair the keys of the Mokamint node, used to sign the blocks that it mines
 	 * @return the Mokamint node
 	 * @throws InterruptedException if the current thread is interrupted before completing the operation
 	 * @throws NodeException if the operation cannot be completed correctly
 	 * @throws TimeoutException if some operation timed out
+	 * @throws InvalidKeyException if the {@code keyPair} is invalid
+	 * @throws SignatureException if the genesis block cannot be signed with {@code keyPair}
 	 */
 	public static MokamintNode resume(MokamintNodeConfig config, LocalNodeConfig mokamintConfig, KeyPair keyPair) throws NodeException, InterruptedException, InvalidKeyException, SignatureException, TimeoutException {
 		return new MokamintNodeImpl(config, mokamintConfig, keyPair, false, false);

io-hotmoka-node-mokamint/src/main/java/io/hotmoka/node/mokamint/internal/MokamintNodeImpl.java

@@ -112,18 +112,19 @@ public class MokamintNodeImpl extends AbstractTrieBasedLocalNode<MokamintNodeImp
 	private final static Logger LOGGER = Logger.getLogger(MokamintNodeImpl.class.getName());
 
 	/**
-	 * Builds a new Hotmoka node based on the Mokamint engine.
+	 * Builds and starts a Mokamint node that uses an already existing store. The consensus
+	 * parameters are recovered from the manifest in the store, hence the store must
+	 * be that of an already initialized blockchain. It spawns the Mokamint engine
+	 * and connects it to an application for handling its transactions.
 	 * 
-	 * @param config the configuration of the node
+	 * @param config the configuration of the Hotmoka node
 	 * @param mokamintConfig the configuration of the underlying Mokamint node
-	 * @param keyPair the key pair of the Mokamint node that will be started
-	 * @param init true if and only if the working directory of the node must be initialized
-	 * @param createGenesis if true, creates a genesis block and starts mining on top (initial synchronization is consequently skipped)
-	 * @throws NodeException if the node is not working properly
+	 * @param keyPair the keys of the Mokamint node, used to sign the blocks that it mines
 	 * @throws InterruptedException if the current thread is interrupted before completing the operation
-	 * @throws SignatureException if the genesis block cannot be signed
-	 * @throws InvalidKeyException if the private key of the node is invalid
+	 * @throws NodeException if the operation cannot be completed correctly
 	 * @throws TimeoutException if some operation timed out
+	 * @throws InvalidKeyException if the {@code keyPair} is invalid
+	 * @throws SignatureException if the genesis block cannot be signed with {@code keyPair}
 	 */
 	public MokamintNodeImpl(MokamintNodeConfig config, LocalNodeConfig mokamintConfig, KeyPair keyPair, boolean init, boolean createGenesis) throws InvalidKeyException, SignatureException, NodeException, InterruptedException, TimeoutException {
 		super(config, init);

io-hotmoka-patricia-api/src/main/java/io/hotmoka/patricia/api/PatriciaTrie.java

@@ -60,6 +60,7 @@ public interface PatriciaTrie<Key, Value, T extends PatriciaTrie<Key, Value, T>>
 	 * 
 	 * @param root the root to use in the cloned trie
 	 * @return the resulting, cloned trie
+	 * @throws UnknownKeyException if {@code root} is unknown in the store of the trie
 	 * @throws TrieException if this Patricia trie is not able to complete the operation correctly
 	 */
 	T checkoutAt(byte[] root) throws UnknownKeyException, TrieException;

io-hotmoka-patricia/src/main/java/io/hotmoka/patricia/AbstractPatriciaTrie.java

@@ -45,7 +45,7 @@ public abstract class AbstractPatriciaTrie<Key, Value, T extends AbstractPatrici
 	 * @param valueToBytes a function that marshals values into their byte representation
 	 * @param bytesToValue a function that unmarshals bytes into the represented value
 	 * @throws TrieException if the creation cannot be completed correctly
-	 * @throws UnknownKeyException 
+	 * @throws UnknownKeyException if {@code root} is unknown in the store of the trie
 	 */
 	protected AbstractPatriciaTrie(KeyValueStore store, byte[] root,
 			Hasher<? super Key> hasherForKeys, HashingAlgorithm hashingForNodes, byte[] hashOfEmpty,
@@ -62,7 +62,7 @@ protected AbstractPatriciaTrie(KeyValueStore store, byte[] root,
 	 *               the given root, that has not been garbage-collected yet
 	 * @param root the root used to check out the trie
 	 * @throws TrieException if the creation cannot be completed correctly
-	 * @throws UnknownKeyException 
+	 * @throws UnknownKeyException if {@code root} is unknown in the store of the trie
 	 */
 	protected AbstractPatriciaTrie(T cloned, byte[] root) throws TrieException, UnknownKeyException {
 		super(cloned, root);

io-hotmoka-patricia/src/main/java/io/hotmoka/patricia/PatriciaTries.java

@@ -47,7 +47,7 @@ private PatriciaTries() {}
 	 * @param <Value> the type of the values of the trie
 	 * @return the trie
 	 * @throws TrieException if the creation cannot be completed correctly
-	 * @throws UnknownKeyException 
+	 * @throws UnknownKeyException if {@code root} is unknown in the store of the trie
 	 */
 	public static <Key, Value> PatriciaTrie<Key, Value, ?> of(KeyValueStore store, byte[] root,
 			Hasher<? super Key> hasherForKeys, HashingAlgorithm hashingForNodes, byte[] hashOfEmpty,

io-hotmoka-patricia/src/main/java/io/hotmoka/patricia/internal/PatriciaTrieImpl.java

@@ -46,7 +46,7 @@ public class PatriciaTrieImpl<Key, Value> extends AbstractPatriciaTrie<Key, Valu
 	 * @param valueToBytes a function that marshals values into their byte representation
 	 * @param bytesToValue a function that unmarshals bytes into the represented value
 	 * @throws TrieException if the creation cannot be completed correctly
-	 * @throws UnknownKeyException 
+	 * @throws UnknownKeyException if {@code root} is unknown in the store of the trie
 	 */
 	public PatriciaTrieImpl(KeyValueStore store, byte[] root,
 			Hasher<? super Key> hasherForKeys, HashingAlgorithm hashingForNodes, byte[] hashOfEmpty,