Clean-up of the Javadocs

io-hotmoka-node-api/src/main/java/io/hotmoka/node/api/ConsensusConfig.java

@@ -45,55 +45,75 @@ public interface ConsensusConfig {
 	String getChainId();
 
 	/**
-	 * Yields the maximal length of the error message kept in the store of the node.
+	 * Yields the maximal length of the error messages kept in the store of the node.
 	 * Beyond this threshold, the message gets truncated.
+	 * 
+	 * @return the maximal length
 	 */
 	long getMaxErrorLength();
 
 	/**
 	 * Yields the maximal number of dependencies in the classpath of a transaction.
+	 * 
+	 * @return the maximal number of dependencies
 	 */
 	long getMaxDependencies();
 
 	/**
 	 * Yields the maximal cumulative size (in bytes) of the instrumented jars of the dependencies
 	 * of a transaction.
+	 * 
+	 * @return the maximal cumulative size (in bytes)
 	 */
 	long getMaxCumulativeSizeOfDependencies();
 
 	/**
 	 * Yields true if and only if the use of the {@code @@SelfCharged} annotation is allowed.
+	 * 
+	 * @return true if and only if the condition holds
 	 */
 	boolean allowsSelfCharged();
 
 	/**
 	 * Yields true if and only if the use of the faucet of the gamete is allowed without a valid signature.
+	 * 
+	 * @return true if and only if the condition holds
 	 */
 	boolean allowsUnsignedFaucet();
 
 	/**
 	 * Yields true if and only if the gamete of the node can call, for free, the add method of the accounts ledger
 	 * and the mint/burn methods of the accounts, without paying gas and without paying for the minted coins.
+	 * 
+	 * @return true if and only if the condition holds
 	 */
 	boolean allowsMintBurnFromGamete();
 
 	/**
 	 * Yields true if and only if the static verification of the classes of the jars installed in the node must be skipped.
+	 * 
+	 * @return true if and only if the condition holds
 	 */
 	boolean skipsVerification();
 
 	/**
 	 * Yields the Base64-encoded public key of the gamete account.
+	 * 
+	 * @return the Base64-encoded public key
 	 */
 	String getPublicKeyOfGamete();
 
 	/**
 	 * Yields the initial gas price.
+	 * 
+	 * @return the initial gas price
 	 */
 	BigInteger getInitialGasPrice();
 
 	/**
 	 * Yields the maximal amount of gas that a non-view transaction can consume.
+	 * 
+	 * @return the maximal amount of gas that a non-view transaction can consume
 	 */
 	BigInteger getMaxGasPerTransaction();
 
@@ -102,13 +122,17 @@ public interface ConsensusConfig {
 	 * Hence requests that specify a lower gas price
 	 * than the current gas price of the node are executed anyway.
 	 * This is mainly useful for testing.
+	 * 
+	 * @return true if and only if the gas price must be ignored
 	 */
 	boolean ignoresGasPrice();
 
 	/**
 	 * Yields the units of gas that are aimed to be rewarded at each reward.
 	 * If the actual reward is smaller, the price of gas must decrease.
 	 * If it is larger, the price of gas must increase.
+	 * 
+	 * @return the units of gas that are aimed to be rewarded at each reward
 	 */
 	BigInteger getTargetGasAtReward();
 
@@ -118,68 +142,95 @@ public interface ConsensusConfig {
 	 * Hence a smaller level means that the latest rewards are heavier
 	 * in the determination of the gas price.
 	 * A value of 0 means that the gas price is constant.
+	 * 
+	 * @return how quick the gas consumed at previous rewards is forgotten:
+	 *         0 means never, 1_000_000 means immediately
 	 */
 	long getOblivion();
 
 	/**
 	 * Yields the initial inflation applied to the gas consumed by transactions before it gets sent
-	 * as reward to the validators. 1,000,000 means 1%.
+	 * as reward. 1,000,000 means 1%.
 	 * Inflation can be negative. For instance, -300,000 means -0.3%.
+	 * 
+	 * @return the initial inflation applied to the gas consumed by transactions; 1,000,000 means 1%
 	 */
 	long getInitialInflation();
 
 	/**
 	 * Yields the version of the verification module to use.
+	 * 
+	 * @return the version of the verification module to use
 	 */
 	long getVerificationVersion();
 
 	/**
 	 * Yields the initial supply of coins in the node.
+	 * 
+	 * @return the initial supply of coins in the node
 	 */
 	BigInteger getInitialSupply();
 
 	/**
 	 * Yields the final supply of coins in the node. Once the current supply reaches
 	 * this final amount, it remains constant.
+	 * 
+	 * @return the final supply of coins in the node
 	 */
 	BigInteger getFinalSupply();
 
 	/**
 	 * Yields the initial supply of red coins in the node.
+	 * 
+	 * @return the initial supply of red coins in the node
 	 */
 	BigInteger getInitialRedSupply();
 
 	/**
-	 * Yields the amount of coin to pay to start a new poll amount the validators,
+	 * Yields the amount of coin to pay to start a new poll amount the voters,
 	 * for instance in order to change a consensus parameter.
+	 * 
+	 * @return the amount of coin to pay to start a new poll
 	 */
 	BigInteger getTicketForNewPoll();
 
 	/**
 	 * Yields the signature algorithm for signing requests.
+	 * 
+	 * @return the signature algorithm
 	 */
 	SignatureAlgorithm<SignedTransactionRequest> getSignature();
 
 	/**
 	 * Yields the amount of validators' rewards that gets staked. The rest is sent to the validators immediately.
 	 * 1000000 = 1%.
+	 * 
+	 * @return the amount of validators' rewards that gets staked; 1000000 = 1%
 	 */
 	int getPercentStaked();
 
 	/**
 	 * Yields extra tax paid when a validator acquires the shares of another validator
 	 * (in percent of the offer cost). 1000000 = 1%.
+	 * 
+	 * @return the extra tax paid when a validator acquires the shares of another validator
+	 *         (in percent of the offer cost). 1000000 = 1%
 	 */
 	int getBuyerSurcharge();
 
 	/**
 	 * Yields the percent of stake that gets slashed for each misbehaving validator. 1000000 means 1%.
+	 * 
+	 * @return the percent of stake that gets slashed for each misbehaving validator. 1000000 means 1%
 	 */
 	int getSlashingForMisbehaving();
 
 	/**
 	 * Yields the percent of stake that gets slashed for validators that do not behave
 	 * (or do not vote). 1000000 means 1%.
+	 * 
+	 * @return the percent of stake that gets slashed for validators that do not behave
+	 *         (or do not vote). 1000000 means 1%
 	 */
 	int getSlashingForNotBehaving();
 

io-hotmoka-node-api/src/main/java/io/hotmoka/node/api/ConsensusConfigBuilder.java

@@ -104,6 +104,7 @@ public interface ConsensusConfigBuilder<T extends ConsensusConfigBuilder<T>> {
 	 * Sets the maximal amount of gas that a non-view transaction can consume.
 	 * It defaults to 1_000_000_000.
 	 * 
+	 * @param maxGasPerTransaction the maximal amount of gas to set
 	 * @return this builder
 	 */
 	T setMaxGasPerTransaction(BigInteger maxGasPerTransaction);
@@ -114,6 +115,7 @@ public interface ConsensusConfigBuilder<T extends ConsensusConfigBuilder<T>> {
 	 * If it is larger, the price of gas must increase.
 	 * It defaults to 1_000_000.
 	 * 
+	 * @param targetGasAtReward the units of gas to set
 	 * @return this builder
 	 */
 	T setTargetGasAtReward(BigInteger targetGasAtReward);
@@ -126,6 +128,7 @@ public interface ConsensusConfigBuilder<T extends ConsensusConfigBuilder<T>> {
 	 * Use 0 to keep the gas price constant.
 	 * It defaults to 250_000L.
 	 * 
+	 * @param oblivion the value to set
 	 * @return this builder
 	 */
 	T setOblivion(long oblivion);
@@ -136,6 +139,7 @@ public interface ConsensusConfigBuilder<T extends ConsensusConfigBuilder<T>> {
 	 * Inflation can be negative. For instance, -300,000 means -0.3%.
 	 * It defaults to 100,000 (that is, inflation is 0.1% by default).
 	 * 
+	 * @param initialInflation the initial inflation to set
 	 * @return this builder
 	 */
 	T setInitialInflation(long initialInflation);
@@ -243,6 +247,9 @@ public interface ConsensusConfigBuilder<T extends ConsensusConfigBuilder<T>> {
 	 * Sets the amount of coins that must be payed to start a new poll amount
 	 * to validators, for instance to change a consensus parameter.
 	 * It defaults to 100.
+	 * 
+	 * @param ticketForNewPoll the amount of coins to set
+	 * @return this builder
 	 */
 	T setTicketForNewPoll(BigInteger ticketForNewPoll);
 

io-hotmoka-node-api/src/main/java/io/hotmoka/node/api/Node.java

@@ -61,6 +61,7 @@ public interface Node extends AutoCloseable {
 	 * already committed.
 	 * 
 	 * @throws NoSuchElementException if the node has not been initialized yet
+	 * @return the reference to the installed Takamaka base classes
 	 */
 	TransactionReference getTakamakaCode() throws NoSuchElementException;
 

io-hotmoka-node-api/src/main/java/io/hotmoka/node/api/Subscription.java

@@ -16,7 +16,7 @@
 
 package io.hotmoka.node.api;
 
-/*
+/**
  * A subscription to events generated by a node.
  */
 public interface Subscription extends AutoCloseable {

io-hotmoka-node/src/main/java/io/hotmoka/node/DeserializationError.java

@@ -22,10 +22,20 @@
 @SuppressWarnings("serial")
 public class DeserializationError extends Error {
 
+	/**
+	 * Creates the exception with the given message.
+	 * 
+	 * @param message the message
+	 */
 	public DeserializationError(String message) {
 		super(message);
 	}
 
+	/**
+	 * Creates the exception with the given cause.
+	 * 
+	 * @param cause the cause
+	 */
 	public DeserializationError(Throwable cause) {
 		super("Cannot deserialize value", cause);
 	}

io-hotmoka-node/src/main/java/io/hotmoka/node/NonWhiteListedCallException.java

@@ -22,6 +22,12 @@
  */
 @SuppressWarnings("serial")
 public class NonWhiteListedCallException extends RuntimeException {
+
+	/**
+	 * Creates the exception with the given message.
+	 * 
+	 * @param message the message
+	 */
 	public NonWhiteListedCallException(String message) {
 		super(message);
 	}

io-hotmoka-node/src/main/java/io/hotmoka/node/OutOfGasError.java

@@ -22,5 +22,9 @@
  */
 @SuppressWarnings("serial")
 public class OutOfGasError extends Error {
+
+	/**
+	 * Creates the exception.
+	 */
 	public OutOfGasError() {}
 }

io-hotmoka-node/src/main/java/io/hotmoka/node/SideEffectsInViewMethodException.java

@@ -20,12 +20,17 @@
 
 /**
  * An exception thrown when a transaction for the execution of a
- * {@link io.takamaka.code.lang.View} method has side-effects different
+ * {@code @@View} method has side-effects different
  * from the modification of the balance of the caller.
  */
 @SuppressWarnings("serial")
 public class SideEffectsInViewMethodException extends Exception {
 
+	/**
+	 * Creates the exception about the given method.
+	 * 
+	 * @param method the method that had unexpected side-effects
+	 */
 	public SideEffectsInViewMethodException(MethodSignature method) {
 		super("@View method " + method + " induced side-effects");
 	}

io-hotmoka-node/src/main/java/io/hotmoka/node/SignatureAlgorithmForTransactionRequests.java

@@ -58,6 +58,9 @@ public static SignatureAlgorithm<SignedTransactionRequest> ed25519() throws NoSu
 	 * It is useful instead for testing, since it makes deterministic the
 	 * sequence of keys of the accounts in the tests and consequently
 	 * also the gas costs of such accounts when they are put into maps, for instance.
+	 * 
+	 * @return the algorithm
+	 * @throws NoSuchAlgorithmException if the installation does not include the ed25519 algorithm
 	 */
 	public static SignatureAlgorithm<SignedTransactionRequest> ed25519det() throws NoSuchAlgorithmException {
 		return SignatureAlgorithms.ed25519det(SignedTransactionRequest::toByteArrayWithoutSignature);