From 36c58b8b67b532b24a2c005457ac7eb03e23c1f2 Mon Sep 17 00:00:00 2001 From: Fausto Spoto Date: Tue, 29 Aug 2023 18:18:19 +0200 Subject: [PATCH] Clean-up of the Javadocs --- .../io/hotmoka/node/api/ConsensusConfig.java | 57 ++++++++++++++++++- .../node/api/ConsensusConfigBuilder.java | 7 +++ .../main/java/io/hotmoka/node/api/Node.java | 1 + .../io/hotmoka/node/api/Subscription.java | 2 +- .../io/hotmoka/node/DeserializationError.java | 10 ++++ .../node/NonWhiteListedCallException.java | 6 ++ .../java/io/hotmoka/node/OutOfGasError.java | 4 ++ .../SideEffectsInViewMethodException.java | 7 ++- ...natureAlgorithmForTransactionRequests.java | 3 + 9 files changed, 92 insertions(+), 5 deletions(-) diff --git a/io-hotmoka-node-api/src/main/java/io/hotmoka/node/api/ConsensusConfig.java b/io-hotmoka-node-api/src/main/java/io/hotmoka/node/api/ConsensusConfig.java index 3a75ada0c..15dea2c0b 100644 --- a/io-hotmoka-node-api/src/main/java/io/hotmoka/node/api/ConsensusConfig.java +++ b/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,6 +122,8 @@ 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(); @@ -109,6 +131,8 @@ public interface ConsensusConfig { * 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 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(); diff --git a/io-hotmoka-node-api/src/main/java/io/hotmoka/node/api/ConsensusConfigBuilder.java b/io-hotmoka-node-api/src/main/java/io/hotmoka/node/api/ConsensusConfigBuilder.java index 93800343b..0ab22d683 100644 --- a/io-hotmoka-node-api/src/main/java/io/hotmoka/node/api/ConsensusConfigBuilder.java +++ b/io-hotmoka-node-api/src/main/java/io/hotmoka/node/api/ConsensusConfigBuilder.java @@ -104,6 +104,7 @@ public interface ConsensusConfigBuilder> { * 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> { * 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> { * 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> { * 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> { * 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); diff --git a/io-hotmoka-node-api/src/main/java/io/hotmoka/node/api/Node.java b/io-hotmoka-node-api/src/main/java/io/hotmoka/node/api/Node.java index 58984541e..84321e0f8 100644 --- a/io-hotmoka-node-api/src/main/java/io/hotmoka/node/api/Node.java +++ b/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; diff --git a/io-hotmoka-node-api/src/main/java/io/hotmoka/node/api/Subscription.java b/io-hotmoka-node-api/src/main/java/io/hotmoka/node/api/Subscription.java index 950d4b7ac..b876f7d2f 100644 --- a/io-hotmoka-node-api/src/main/java/io/hotmoka/node/api/Subscription.java +++ b/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 { diff --git a/io-hotmoka-node/src/main/java/io/hotmoka/node/DeserializationError.java b/io-hotmoka-node/src/main/java/io/hotmoka/node/DeserializationError.java index 25b05568c..588c42997 100644 --- a/io-hotmoka-node/src/main/java/io/hotmoka/node/DeserializationError.java +++ b/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); } diff --git a/io-hotmoka-node/src/main/java/io/hotmoka/node/NonWhiteListedCallException.java b/io-hotmoka-node/src/main/java/io/hotmoka/node/NonWhiteListedCallException.java index 97dbdadf4..ae881a038 100644 --- a/io-hotmoka-node/src/main/java/io/hotmoka/node/NonWhiteListedCallException.java +++ b/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); } diff --git a/io-hotmoka-node/src/main/java/io/hotmoka/node/OutOfGasError.java b/io-hotmoka-node/src/main/java/io/hotmoka/node/OutOfGasError.java index 22698d10f..88a004604 100644 --- a/io-hotmoka-node/src/main/java/io/hotmoka/node/OutOfGasError.java +++ b/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() {} } \ No newline at end of file diff --git a/io-hotmoka-node/src/main/java/io/hotmoka/node/SideEffectsInViewMethodException.java b/io-hotmoka-node/src/main/java/io/hotmoka/node/SideEffectsInViewMethodException.java index 69b1eb85c..2e881f1ce 100644 --- a/io-hotmoka-node/src/main/java/io/hotmoka/node/SideEffectsInViewMethodException.java +++ b/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"); } diff --git a/io-hotmoka-node/src/main/java/io/hotmoka/node/SignatureAlgorithmForTransactionRequests.java b/io-hotmoka-node/src/main/java/io/hotmoka/node/SignatureAlgorithmForTransactionRequests.java index 8734ff5ce..324bab749 100644 --- a/io-hotmoka-node/src/main/java/io/hotmoka/node/SignatureAlgorithmForTransactionRequests.java +++ b/io-hotmoka-node/src/main/java/io/hotmoka/node/SignatureAlgorithmForTransactionRequests.java @@ -58,6 +58,9 @@ public static SignatureAlgorithm 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 ed25519det() throws NoSuchAlgorithmException { return SignatureAlgorithms.ed25519det(SignedTransactionRequest::toByteArrayWithoutSignature);