Merge pull request #316 from kleros/review/linguo

review: Matt's linguo review

Author: unknownunknown1

contracts/standard/arbitration/Linguo.sol

@@ -1,14 +1,14 @@
 /**
  *  @authors: [@unknownunknown1]
- *  @reviewers: [@ferittuncer*, @clesaege*, @satello*, @hbarcelos]
+ *  @reviewers: [@ferittuncer*, @clesaege*, @satello*, @hbarcelos, @mtsalenc]
  *  @auditors: []
  *  @bounties: []
  *  @deployments: []
  */
 
 /* solium-disable security/no-block-members */
 /* solium-disable max-len*/
-pragma solidity ^0.4.24;
+pragma solidity ^0.4.26;
 
 import "./Arbitrable.sol";
 import "../../libraries/CappedMath.sol";
@@ -81,8 +81,8 @@ contract Linguo is Arbitrable {
     event TaskCreated(uint indexed _taskID, address indexed _requester, uint _timestamp);
 
     /** @dev To be emitted when a translator assigns the task to himself.
-     *  @param _taskID The ID of the newly created task.
-     *  @param _translator The address that assigned to the task.
+     *  @param _taskID The ID of the assigned task.
+     *  @param _translator The address that was assigned to the task.
      *  @param _price The task price at the moment it was assigned.
      *  @param _timestamp When the task was assigned.
      */
@@ -110,9 +110,9 @@ contract Linguo is Arbitrable {
      */
     event TaskResolved(uint indexed _taskID, string _reason, uint _timestamp);
 
-    /** @dev To be emitted when one of the parties successfully paid its appeal fees.
+    /** @dev To be emitted when the appeal fees of one of the parties are fully funded.
      *  @param _taskID The ID of the respective task.
-     *  @param _party The party that paid appeal fees.
+     *  @param _party The party that is fully funded.
      */
     event HasPaidAppealFee(uint indexed _taskID, Party _party);
 
@@ -180,21 +180,21 @@ contract Linguo is Arbitrable {
         challengeMultiplier = _challengeMultiplier;
     }
 
-    /** @dev Changes the percentage of arbitration fees that must be paid by parties if there was no winner and loser in previous round.
+    /** @dev Changes the percentage of arbitration fees that must be paid by parties as a fee stake if there was no winner and loser in the previous round.
      *  @param _sharedStakeMultiplier A new value of the multiplier of the appeal cost in case when there is no winner/loser in previous round. In basis point.
      */
     function changeSharedStakeMultiplier(uint _sharedStakeMultiplier) public onlyGovernor {
         sharedStakeMultiplier = _sharedStakeMultiplier;
     }
 
-    /** @dev Changes the percentage of arbitration fees that must be paid by the party that won the previous round.
+    /** @dev Changes the percentage of arbitration fees that must be paid as a fee stake by the party that won the previous round.
      *  @param _winnerStakeMultiplier A new value of the multiplier of the appeal cost that the winner of the previous round has to pay. In basis points.
      */
     function changeWinnerStakeMultiplier(uint _winnerStakeMultiplier) public onlyGovernor {
         winnerStakeMultiplier = _winnerStakeMultiplier;
     }
 
-    /** @dev Changes the percentage of arbitration fees that must be paid by the party that lost the previous round.
+    /** @dev Changes the percentage of arbitration fees that must be paid as a fee stake by the party that lost the previous round.
      *  @param _loserStakeMultiplier A new value of the multiplier of the appeal cost that the party that lost the previous round has to pay. In basis points.
      */
     function changeLoserStakeMultiplier(uint _loserStakeMultiplier) public onlyGovernor {
@@ -242,10 +242,10 @@ contract Linguo is Arbitrable {
 
         uint price = task.minPrice + (task.maxPrice - task.minPrice) * (now - task.lastInteraction) / task.submissionTimeout;
         uint arbitrationCost = arbitrator.arbitrationCost(arbitratorExtraData);
-        uint deposit = arbitrationCost.addCap((translationMultiplier.mulCap(price)) / MULTIPLIER_DIVISOR);
+        uint translatorDeposit = arbitrationCost.addCap((translationMultiplier.mulCap(price)) / MULTIPLIER_DIVISOR);
 
         require(task.status == Status.Created, "Task has already been assigned or reimbursed.");
-        require(msg.value >= deposit, "Not enough ETH to reach the required deposit value.");
+        require(msg.value >= translatorDeposit, "Not enough ETH to reach the required deposit value.");
 
         task.parties[uint(Party.Translator)] = msg.sender;
         task.status = Status.Assigned;
@@ -254,9 +254,9 @@ contract Linguo is Arbitrable {
         task.requester.send(remainder);
         // Update requester's deposit since we reimbursed him the difference between maximal and actual price.
         task.requesterDeposit = price;
-        task.sumDeposit += deposit;
+        task.sumDeposit += translatorDeposit;
 
-        remainder = msg.value - deposit;
+        remainder = msg.value - translatorDeposit;
         msg.sender.send(remainder);
 
         emit TaskAssigned(_taskID, msg.sender, price, now);
@@ -463,8 +463,8 @@ contract Linguo is Arbitrable {
             withdrawFeesAndRewards(_beneficiary, _taskID, i);
     }
 
-    /** @dev Gives a ruling for a dispute. Must be called by the arbitrator.
-     *  The purpose of this function is to ensure that the address calling it has the right to rule on the contract.
+    /** @dev Gives a ruling for a dispute. Can only be called by the arbitrator.
+     *  The purpose of this function is to ensure that the address calling it has the right to rule on the contract and to invert the ruling in the case a party loses from lack of appeal fees funding.
      *  @param _disputeID ID of the dispute in the Arbitrator contract.
      *  @param _ruling Ruling given by the arbitrator. Note that 0 is reserved for "Refuse to arbitrate".
      */