Merge pull request #14 from kleros/refactor/docs-and-error-messages

docs: add return docs + error messages

Author: fnanni-0

.node-version

@@ -1 +1 @@
-10.23.0
+10.24.1

contracts/kleros/xKlerosLiquid.sol

@@ -176,7 +176,7 @@ contract xKlerosLiquid is Initializable, TokenController, Arbitrator {
 
     // Dispute
     // Use a mapping instead of an array so that upgrading (appending variables to) the Dispute struct is possible without big layout changes.
-    mapping(uint => Dispute) public disputes; // The disputes. 
+    mapping(uint => Dispute) public disputes; // The disputes.
     uint public totalDisputes;
 
     // Juror
@@ -395,9 +395,9 @@ contract xKlerosLiquid is Initializable, TokenController, Arbitrator {
         if (phase == Phase.staking) {
             require(now - lastPhaseChange >= minStakingTime, "The minimum staking time has not passed yet.");
             require(disputesWithoutJurors > 0, "There are no disputes that need jurors.");
-            /** collectRoundLength is added so that the last validator to reveal cannot know 
+            /** collectRoundLength is added so that the last validator to reveal cannot know
              *  during the staking phase which random seed is going to be used in the drawing phase.
-             */ 
+             */
             RNBlock = RNGenerator.nextCommitPhaseStartBlock() + RNGenerator.collectRoundLength();
             phase = Phase.generating;
         } else if (phase == Phase.generating) {

contracts/tokens/WrappedPinakion.sol

@@ -1,7 +1,7 @@
 /**
  *  https://contributing.kleros.io/smart-contract-workflow
  *  @authors: [@fnanni-0]
- *  @reviewers: [@unknownunknown1, @MerlinEgalite, @hbarcelos*, @shalzz]
+ *  @reviewers: [@unknownunknown1, @MerlinEgalite, @hbarcelos, @shalzz]
  *  @auditors: []
  *  @bounties: []
  *  @deployments: []
@@ -119,7 +119,7 @@ contract WrappedPinakion is Initializable {
      * someone invoking `relayTokensAndCall()` on the Foreign bridge contract.
      * @param _token The token address the _amount belongs to.
      * @param _amount The amount of wrapped PNK to mint.
-     * @param _data Calldata containing the address of the recipient. 
+     * @param _data Calldata containing the address of the recipient.
      * Notice that the address has to be padded to the right 32 bytes.
      */
     function onTokenBridged(
@@ -165,10 +165,14 @@ contract WrappedPinakion is Initializable {
      * @notice Moves `_amount` tokens from the caller's account to `_recipient`.
      * @param _recipient The entity receiving the funds.
      * @param _amount The amount to tranfer in base units.
+     * @return True on success.
      */
     function transfer(address _recipient, uint256 _amount) public returns (bool) {
         if (isContract(controller)) {
-            require(TokenController(controller).onTransfer(msg.sender, _recipient, _amount));
+            require(
+                TokenController(controller).onTransfer(msg.sender, _recipient, _amount),
+                "Token controller rejects transfer."
+            );
         }
         balances[msg.sender] = balances[msg.sender].sub(_amount); // ERC20: transfer amount exceeds balance
         balances[_recipient] = balances[_recipient].add(_amount);
@@ -182,14 +186,18 @@ contract WrappedPinakion is Initializable {
      * @param _sender The entity to take the funds from.
      * @param _recipient The entity receiving the funds.
      * @param _amount The amount to tranfer in base units.
+     * @return True on success.
      */
     function transferFrom(
         address _sender,
         address _recipient,
         uint256 _amount
     ) public returns (bool) {
         if (isContract(controller)) {
-            require(TokenController(controller).onTransfer(_sender, _recipient, _amount));
+            require(
+                TokenController(controller).onTransfer(_sender, _recipient, _amount),
+                "Token controller rejects transfer."
+            );
         }
 
         /** The controller of this contract can move tokens around at will,
@@ -211,6 +219,7 @@ contract WrappedPinakion is Initializable {
      * @notice Approves `_spender` to spend `_amount`.
      * @param _spender The entity allowed to spend funds.
      * @param _amount The amount of base units the entity will be allowed to spend.
+     * @return True on success.
      */
     function approve(address _spender, uint256 _amount) public returns (bool) {
         // Alerts the token controller of the approve function call
@@ -230,6 +239,7 @@ contract WrappedPinakion is Initializable {
      * @notice Increases the `_spender` allowance by `_addedValue`.
      * @param _spender The entity allowed to spend funds.
      * @param _addedValue The amount of extra base units the entity will be allowed to spend.
+     * @return True on success.
      */
     function increaseAllowance(address _spender, uint256 _addedValue) public returns (bool) {
         uint256 newAllowance = allowance[msg.sender][_spender].add(_addedValue);
@@ -250,6 +260,7 @@ contract WrappedPinakion is Initializable {
      * @notice Decreases the `_spender` allowance by `_subtractedValue`.
      * @param _spender The entity whose spending allocation will be reduced.
      * @param _subtractedValue The reduction of spending allocation in base units.
+     * @return True on success.
      */
     function decreaseAllowance(address _spender, uint256 _subtractedValue) public returns (bool) {
         uint256 newAllowance = allowance[msg.sender][_spender].sub(_subtractedValue); // ERC20: decreased allowance below zero
@@ -287,7 +298,10 @@ contract WrappedPinakion is Initializable {
      */
     function _burn(uint256 _amount) internal {
         if (isContract(controller)) {
-            require(TokenController(controller).onTransfer(msg.sender, address(0x0), _amount));
+            require(
+                TokenController(controller).onTransfer(msg.sender, address(0x0), _amount),
+                "Token controller rejects transfer."
+            );
         }
         balances[msg.sender] = balances[msg.sender].sub(_amount); // ERC20: burn amount exceeds balance
         totalSupply = totalSupply.sub(_amount);

package.json

@@ -40,7 +40,7 @@
     "mocha": "^8.1.1",
     "npm-run-all": "^4.1.5",
     "prettier": "2.3.0",
-    "prettier-plugin-solidity": "^1.0.0-beta.10",
+    "prettier-plugin-solidity": "1.0.0-beta.6",
     "solhint": "^3.3.4",
     "solhint-plugin-prettier": "^0.0.5",
     "solidity-coverage": "^0.5.11",

yarn.lock

@@ -1916,9 +1916,16 @@
   integrity sha512-9NET910DNaIPngYnLLPeg+Ogzqsi9uM4mSboU5y6p8S5DzMTVEsJZrawi+BoDNUVBa2DhJqQYUFvMDfgU062LQ==
 
 "@solidity-parser/parser@^0.12.0":
-  version "0.12.0"
-  resolved "https://registry.yarnpkg.com/@solidity-parser/parser/-/parser-0.12.0.tgz#18a0fb2a9d2484b23176f63b16093c64794fc323"
-  integrity sha512-DT3f/Aa4tQysZwUsuqBwvr8YRJzKkvPUKV/9o2/o5EVw3xqlbzmtx4O60lTUcZdCawL+N8bBLNUyOGpHjGlJVQ==
+  version "0.12.2"
+  resolved "https://registry.yarnpkg.com/@solidity-parser/parser/-/parser-0.12.2.tgz#1afad367cb29a2ed8cdd4a3a62701c2821fb578f"
+  integrity sha512-d7VS7PxgMosm5NyaiyDJRNID5pK4AWj1l64Dbz0147hJgy5k2C0/ZiKK/9u5c5K+HRUVHmp+RMvGEjGh84oA5Q==
+
+"@solidity-parser/parser@^0.13.2":
+  version "0.13.2"
+  resolved "https://registry.yarnpkg.com/@solidity-parser/parser/-/parser-0.13.2.tgz#b6c71d8ca0b382d90a7bbed241f9bc110af65cbe"
+  integrity sha512-RwHnpRnfrnD2MSPveYoPh8nhofEvX7fgjHk1Oq+NNvCcLx4r1js91CO9o+F/F3fBzOCyvm8kKRTriFICX/odWw==
+  dependencies:
+    antlr4ts "^0.5.0-alpha.4"
 
 "@solidity-parser/parser@^0.8.0":
   version "0.8.2"
@@ -2684,6 +2691,11 @@ [email protected]:
   resolved "https://registry.yarnpkg.com/antlr4/-/antlr4-4.7.1.tgz#69984014f096e9e775f53dd9744bf994d8959773"
   integrity sha512-haHyTW7Y9joE5MVs37P2lNYfU2RWBLfcRDD8OWldcdZm5TiCE91B5Xl1oWSwiDUSd4rlExpt2pu1fksYQjRBYQ==
 
+antlr4ts@^0.5.0-alpha.4:
+  version "0.5.0-alpha.4"
+  resolved "https://registry.yarnpkg.com/antlr4ts/-/antlr4ts-0.5.0-alpha.4.tgz#71702865a87478ed0b40c0709f422cf14d51652a"
+  integrity sha512-WPQDt1B74OfPv/IMS2ekXAKkTZIHl88uMetg6q3OTqgFxZ/dxDXI0EWLyZid/1Pe6hTftyg5N7gel5wNAGxXyQ==
+
 [email protected], any-promise@^1.0.0, any-promise@^1.3.0:
   version "1.3.0"
   resolved "https://registry.yarnpkg.com/any-promise/-/any-promise-1.3.0.tgz#abc6afeedcea52e809cdc0376aed3ce39635d17f"
@@ -12004,7 +12016,7 @@ prettier-linter-helpers@^1.0.0:
   dependencies:
     fast-diff "^1.1.2"
 
-prettier-plugin-solidity@^1.0.0-alpha.56:
+[email protected]beta.6:
   version "1.0.0-beta.6"
   resolved "https://registry.yarnpkg.com/prettier-plugin-solidity/-/prettier-plugin-solidity-1.0.0-beta.6.tgz#aa7b14a60cd6e22e46db75c84d836b569fb63f65"
   integrity sha512-WymLqd22Hl93t5+HDNLk08TAWp4i4vZMhpihuVqkwOApjCT7mH1qwhLtvf3m+NdU//qj8vrPDmMoT+xc74skcg==
@@ -12018,16 +12030,26 @@ prettier-plugin-solidity@^1.0.0-alpha.56:
     solidity-comments-extractor "^0.0.4"
     string-width "^4.2.0"
 
+[email protected]:
+  version "2.3.0"
+  resolved "https://registry.yarnpkg.com/prettier/-/prettier-2.3.0.tgz#b6a5bf1284026ae640f17f7ff5658a7567fc0d18"
+  integrity sha512-kXtO4s0Lz/DW/IJ9QdWhAf7/NmPWQXkFr/r/WkR3vyI+0v8amTDxiaQSLzs8NBlytfLWX/7uQUMIW677yLKl4w==
+
 prettier@^1.14.3:
   version "1.19.1"
   resolved "https://registry.yarnpkg.com/prettier/-/prettier-1.19.1.tgz#f7d7f5ff8a9cd872a7be4ca142095956a60797cb"
   integrity sha512-s7PoyDv/II1ObgQunCbB9PdLmUcBZcnWOcxDh7O0N/UwDEsHyqkW+Qh28jW+mVuCdx7gLB0BotYI1Y6uI9iyew==
 
-prettier@^2.0.5, prettier@^2.1.2, prettier@^2.2.1:
+prettier@^2.1.2:
   version "2.2.1"
   resolved "https://registry.yarnpkg.com/prettier/-/prettier-2.2.1.tgz#795a1a78dd52f073da0cd42b21f9c91381923ff5"
   integrity sha512-PqyhM2yCjg/oKkFPtTGUojv7gnZAoG80ttl45O6x2Ug/rMJw4wcc9k6aaf2hibP7BGVCCM33gZoGjyvt9mm16Q==
 
+prettier@^2.2.1:
+  version "2.3.1"
+  resolved "https://registry.yarnpkg.com/prettier/-/prettier-2.3.1.tgz#76903c3f8c4449bc9ac597acefa24dc5ad4cbea6"
+  integrity sha512-p+vNbgpLjif/+D+DwAZAbndtRrR0md0MwfmOVN9N+2RgyACMT+7tfaRnT+WDPkqnuVwleyuBIG2XBxKDme3hPA==
+
 private@^0.1.6, private@^0.1.8:
   version "0.1.8"
   resolved "https://registry.yarnpkg.com/private/-/private-0.1.8.tgz#2381edb3689f7a53d653190060fcf822d2f368ff"
@@ -13394,19 +13416,19 @@ solc@^0.6.3:
     semver "^5.5.0"
     tmp "0.0.33"
 
-solhint-plugin-prettier@^0.0.4:
-  version "0.0.4"
-  resolved "https://registry.yarnpkg.com/solhint-plugin-prettier/-/solhint-plugin-prettier-0.0.4.tgz#ab55ff776d64ff665c52bed41a3b4795c391c9d8"
-  integrity sha512-JVxh8ZkD4ydb0EndbNcstpFU+vWzUvX3jr9z6u72+Srg/zjD8JQ1tIMjMn0H1PnsNLItZqPZ6RYIPJB6HOsVMg==
+solhint-plugin-prettier@^0.0.5:
+  version "0.0.5"
+  resolved "https://registry.yarnpkg.com/solhint-plugin-prettier/-/solhint-plugin-prettier-0.0.5.tgz#e3b22800ba435cd640a9eca805a7f8bc3e3e6a6b"
+  integrity sha512-7jmWcnVshIrO2FFinIvDQmhQpfpS2rRRn3RejiYgnjIE68xO2bvrYvjqVNfrio4xH9ghOqn83tKuTzLjEbmGIA==
   dependencies:
     prettier-linter-helpers "^1.0.0"
 
-solhint@^3.2.0:
-  version "3.3.4"
-  resolved "https://registry.yarnpkg.com/solhint/-/solhint-3.3.4.tgz#81770c60eeb027e6e447cb91ed599baf5e888e09"
-  integrity sha512-AEyjshF/PC6kox1c1l79Pji+DK9WVuk5u2WEh6bBKt188gWa63NBOAgYg0fBRr5CTUmsuGc1sGH7dgUVs83mKw==
+solhint@^3.3.4:
+  version "3.3.6"
+  resolved "https://registry.yarnpkg.com/solhint/-/solhint-3.3.6.tgz#abe9af185a9a7defefba480047b3e42cbe9a1210"
+  integrity sha512-HWUxTAv2h7hx3s3hAab3ifnlwb02ZWhwFU/wSudUHqteMS3ll9c+m1FlGn9V8ztE2rf3Z82fQZA005Wv7KpcFA==
   dependencies:
-    "@solidity-parser/parser" "^0.12.0"
+    "@solidity-parser/parser" "^0.13.2"
     ajv "^6.6.1"
     antlr4 "4.7.1"
     ast-parents "0.0.1"