docs: add return docs + error messages

Author: fnanni-0

contracts/tokens/WrappedPinakion.sol

@@ -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);