Improve documentation in several methods (#536)

contracts/ERC677BridgeTokenRewardable.sol

@@ -13,11 +13,29 @@ contract ERC677BridgeTokenRewardable is ERC677MultiBridgeToken {
         // solhint-disable-previous-line no-empty-blocks
     }
 
+    /**
+     * @dev Updates the address of the used block reward contract.
+     * Only the token owner can call this method. 
+     * Even though this function is inteded only for the initialization purpose,
+     * it is still possible to change the already used block reward contract.
+     * In this case users of the old contract won't lose their accumulated rewards,
+     * they can proceed with the withdrawal by calling the old block reward contract directly.
+     * @param _blockRewardContract address of the new block reward contract.
+     */
     function setBlockRewardContract(address _blockRewardContract) external onlyOwner {
         require(AddressUtils.isContract(_blockRewardContract));
         blockRewardContract = _blockRewardContract;
     }
 
+    /**
+     * @dev Updates the address of the used staking contract.
+     * Only the token owner can call this method. 
+     * Even though this function is inteded only for the initialization purpose,
+     * it is still possible to change the already used staking contract.
+     * In this case users of the old staking contract won't lose their tokens,
+     * they can proceed with the withdrawal by calling the old staking contract directly.
+     * @param _stakingContract address of the new staking contract.
+     */
     function setStakingContract(address _stakingContract) external onlyOwner {
         require(AddressUtils.isContract(_stakingContract));
         require(balanceOf(_stakingContract) == 0);

contracts/PermittableToken.sol

@@ -98,6 +98,8 @@ contract PermittableToken is ERC677BridgeToken {
     /// @param _nonce The nonce taken from `nonces(_holder)` public getter.
     /// @param _expiry The allowance expiration date (unix timestamp in UTC).
     /// Can be zero for no expiration. Forced to zero if `_allowed` is `false`.
+    /// Note that timestamps are not precise, malicious miner/validator can manipulate them to some extend.
+    /// Assume that there can be a 900 seconds time delta between the desired timestamp and the actual expiration.
     /// @param _allowed True to enable unlimited allowance for the spender by the holder. False to disable.
     /// @param _v A final byte of signature (ECDSA component).
     /// @param _r The first 32 bytes of signature (ECDSA component).

contracts/libraries/Message.sol

@@ -2,26 +2,6 @@ pragma solidity 0.4.24;
 import "../interfaces/IBridgeValidators.sol";
 
 library Message {
-    // function uintToString(uint256 inputValue) internal pure returns (string) {
-    //     // figure out the length of the resulting string
-    //     uint256 length = 0;
-    //     uint256 currentValue = inputValue;
-    //     do {
-    //         length++;
-    //         currentValue /= 10;
-    //     } while (currentValue != 0);
-    //     // allocate enough memory
-    //     bytes memory result = new bytes(length);
-    //     // construct the string backwards
-    //     uint256 i = length - 1;
-    //     currentValue = inputValue;
-    //     do {
-    //         result[i--] = byte(48 + currentValue % 10);
-    //         currentValue /= 10;
-    //     } while (currentValue != 0);
-    //     return string(result);
-    // }
-
     function addressArrayContains(address[] array, address value) internal pure returns (bool) {
         for (uint256 i = 0; i < array.length; i++) {
             if (array[i] == value) {

contracts/libraries/TokenReader.sol

@@ -73,7 +73,7 @@ library TokenReader {
             ptr := mload(0x40)
             mstore(ptr, 0x95d89b4100000000000000000000000000000000000000000000000000000000) // symbol()
             if iszero(staticcall(gas, _token, ptr, 4, ptr, 32)) {
-                mstore(ptr, 0xf76f8d7800000000000000000000000000000000000000000000000000000000) // SYMBOl()
+                mstore(ptr, 0xf76f8d7800000000000000000000000000000000000000000000000000000000) // SYMBOL()
                 staticcall(gas, _token, ptr, 4, ptr, 32)
                 pop
             }

contracts/upgradeable_contracts/BaseMediatorFeeManager.sol

@@ -32,7 +32,7 @@ contract BaseMediatorFeeManager is Ownable {
     * @dev Stores the initial parameters of the fee manager.
     * @param _owner address of the owner of the fee manager contract.
     * @param _fee the fee percentage amount.
-    * @param _rewardAccountList list of addresses that will receive the fee rewards.
+    * @param _rewardAccountList list of unique addresses that will receive the fee rewards.
     * @param _mediatorContract address of the mediator contract used together with this fee manager.
     */
     constructor(address _owner, uint256 _fee, address[] _rewardAccountList, address _mediatorContract) public {

contracts/upgradeable_contracts/arbitrary_message/BasicAMB.sol

@@ -106,6 +106,11 @@ contract BasicAMB is BasicBridge, VersionableAMB {
     function _setChainIds(uint256 _sourceChainId, uint256 _destinationChainId) internal {
         require(_sourceChainId > 0 && _destinationChainId > 0);
         require(_sourceChainId != _destinationChainId);
+
+        // Length fields are needed further when encoding the message.
+        // Chain ids are compressed, so that leading zero bytes are not preserved.
+        // In order to save some gas during calls to MessageDelivery.c,
+        // lengths of chain ids are precalculated and being saved in the storage.
         uint256 sourceChainIdLength = 0;
         uint256 destinationChainIdLength = 0;
         uint256 mask = 0xff;

contracts/upgradeable_contracts/multi_amb_erc20_to_erc677/BasicMultiTokenBridge.sol

@@ -276,6 +276,9 @@ contract BasicMultiTokenBridge is EternalStorage, Ownable {
             // e.g. minPerTx(address(0)) == 10 ** 14, _decimals == 3. _minPerTx happens to be 0, which is not allowed.
             // in this case, limits are raised to the default values
             if (_minPerTx == 0) {
+                // Numbers 1, 100, 10000 are chosen in a semi-random way,
+                // so that any token with small decimals can still be bridged in some amounts.
+                // It is possible to override limits for the particular token later if needed.
                 _minPerTx = 1;
                 if (_maxPerTx <= _minPerTx) {
                     _maxPerTx = 100;