Refactor/reviewing contract code and comments

packages/kosu-system-contracts/README.md

@@ -43,3 +43,20 @@ Below are the deployed addresses for the core Kosu protocol contract system on t
 | [PosterRegistry](./contracts/poster/PosterRegistry.sol)                   | 08/19/19         | 0x7e6534b8205713246e91a14b462d2dbcac3ede17 |
 | [ValidatorRegistry](./contracts/validator/ValidatorRegistry.sol)          | 08/19/19         | 0x301bb008f2a8a3cae9918743fe43428551392773 |
 | [ZeroExV2SubContract](./contracts/sub-contracts/ZeroExV2SubContract.sol)  | 08/19/19         | 0x0265e7d1b094787cb13174e18a1cefc41279a6c9 |
+
+### Kosu CI Test
+
+-   **Network ID:** 6175
+-   **ETHNET URL:** `http://kosu-geth:8545`
+
+| Contract Name                                                             | Last Deploy Date | Deployed Address                           |
+| ------------------------------------------------------------------------- | ---------------- | ------------------------------------------ |
+| [OrderGateway](./contracts/external/OrderGateway.sol)                     | 08/20/19         | 0xb8fda6341f80cbae987ab5cd00dce502097e3152 |
+| [AuthorizedAddresses](./contracts/access_control/AuthorizedAddresses.sol) | 08/20/19         | 0xe473109cb41c773fd2fe01e83c6e51356f9585d6 |
+| [EventEmitter](./contracts/event/EventEmitter.sol)                        | 08/20/19         | 0x2f3afeff0914f33769cdfbf3fcf870c33b26c311 |
+| [KosuToken](./contracts/lib/KosuToken.sol)                                | 08/20/19         | 0xcc868306d6188b2b12757a7c3926042b4d3c4e29 |
+| [Treasury](./contracts/treasury/Treasury.sol)                             | 08/20/19         | 0x46572f9082dd2429c2c138fa9483a67d4f29d423 |
+| [Voting](./contracts/voting/Voting.sol)                                   | 08/20/19         | 0x5d60c93d8b48682cd387c8be7e9461b67ecfbea1 |
+| [PosterRegistry](./contracts/poster/PosterRegistry.sol)                   | 08/20/19         | 0x7e6534b8205713246e91a14b462d2dbcac3ede17 |
+| [ValidatorRegistry](./contracts/validator/ValidatorRegistry.sol)          | 08/20/19         | 0x301bb008f2a8a3cae9918743fe43428551392773 |
+| [ZeroExV2SubContract](./contracts/sub-contracts/ZeroExV2SubContract.sol)  | 08/20/19         | 0x0265e7d1b094787cb13174e18a1cefc41279a6c9 |

packages/kosu-system-contracts/contracts/access_control/AuthorizedAddresses.sol

@@ -4,42 +4,42 @@ import "openzeppelin-solidity/contracts/ownership/Ownable.sol";
 
 /** @title AuthorizedAddresses
     @author Freydal
-    @dev Common registry of system contract addresses authrorized to access internal methods.
+    @dev Common registry of system contract addresses authorized to access internal methods.
 */
 contract AuthorizedAddresses is Ownable {
 
     // Mapping storing address permissions
     mapping(address => bool) private authorizedAddresses;
 
-    /** @dev Constructor initializes with the creator permission set to true.
-        @notice Constructor initializes with the creator permission set to true.
+    /** @dev Initializes contract with the creators permissions set to true.
+        @notice Initializes contract with the creators permissions set to true.
     */
     constructor() Ownable() public {
         authorizedAddresses[owner()] = true;
     }
 
     /** @dev Authorizes the address by setting the mapping value to true.
-        @notice Authorizes the address by setting the mapping value to true
+        @notice Authorizes the address by setting the mapping value to true.
         @param a Address to authorize
     */
     function authorizeAddress(address a) public {
         require(authorizedAddresses[msg.sender]);
         authorizedAddresses[a] = true;
     }
 
-    /** @dev Unauthorizes the address by setting the mapping value to false.
-        @notice Unauthorizes the address by setting the mapping value to false
+    /** @dev Disables the address previous authorization by setting the mapping value to false.
+        @notice Disables the address previous authorization by setting the mapping value to false
         @param a Address to unauthorize
     */
     function unauthorizeAddress(address a) public {
         require(authorizedAddresses[msg.sender]);
         authorizedAddresses[a] = false;
     }
 
-    /** @dev Verify if address is authorized by reading contract mapping
-        @notice Verify if address is authorized by reading contract mapping
-        @param a Address to get authorized value.
-        @return True if the address is authorized, false otherwise.
+    /** @dev Verify address authorization.
+        @notice Verify address authorization.
+        @param a Address to authorize.
+        @return Address authorization
     */
     function isAddressAuthorized(address a) public view returns (bool) {
         return authorizedAddresses[a];

packages/kosu-system-contracts/contracts/base/Authorizable.sol

@@ -4,7 +4,7 @@ import "../access_control/AuthorizedAddresses.sol";
 
 /** @title Authorizable
     @author Freydal
-    @dev Implements a modifier to restrict function access based on the state of the AuthorizedAddresses registry.
+    @dev Implements a modifier to verify authorization with the AuthorizedAddresses contract
 */
 contract Authorizable {
 
@@ -19,8 +19,8 @@ contract Authorizable {
         authorizedAddress = AuthorizedAddresses(authorizedAddressesAddress);
     }
 
-    /** @dev Ensures msg.sender is from an address enabled for system level access.
-        @notice Ensures msg.sender is from an address enabled for system level access.
+    /** @dev Ensures msg.sender is authorized within the AuthorizedAddresses contract
+        @notice Ensures msg.sender is authorized within the AuthorizedAddresses contract
     */
     modifier isAuthorized() {
         require(authorizedAddress.isAddressAuthorized(msg.sender));

packages/kosu-system-contracts/contracts/event/EventEmitter.sol

@@ -4,11 +4,11 @@ import "../base/Authorizable.sol";
 
 /** @title EventEmitter
     @author Freydal
-    @dev A shared contract for all Kosu system contracts to trigger event logs through.
+    @dev A central event emitting contract supporting the Kosu contract system.
 */
 contract EventEmitter is Authorizable {
 
-    /// Generic event which can be decoded in Javascript via internal library.
+    // Generic Kosu Event
     event KosuEvent(string eventType, bytes32[] data, string stringData);
 
     /** @dev Event emitter instantiated with Authorizable.
@@ -18,11 +18,11 @@ contract EventEmitter is Authorizable {
     constructor(address auth) Authorizable(auth) public {
     }
 
-    /** @dev Emit generic events which can have decoding exposed though javascript library.
-        @notice Emit generic events which can have decoding exposed though javascript library.
-        @param eventType String name/type of event
-        @param data Bytes32 encoded data to be emitted from a centralized location
-        @param stringData String containing optional additonal information
+    /** @dev Emits a standard event from the Kosu contract system.  The events can be decoded though the Kosu.js library.
+        @notice Emits a standard event from the Kosu contract system.  The events can be decoded though the Kosu.js library.
+        @param eventType String name/type of event.
+        @param data Bytes32 encoded data to be emitted.
+        @param stringData String containing optional additional information.
     */
     function emitEvent(string calldata eventType, bytes32[] calldata data, string calldata stringData) external isAuthorized {
         emit KosuEvent(eventType, data, stringData);

packages/kosu-system-contracts/contracts/external/OrderGateway.sol

@@ -4,50 +4,44 @@ import "@kosu/subcontract-sdk/contracts/SubContract.sol";
 
 /** @title OrderGateway
     @author Freydal
-    @dev Access SubContract implementation's methods to participate in trades and check order status.
+    @dev Serves as a message router for SubContract implementations.  Passing SubContract method calls through the gateway allows for a single watch point for incoming participate transactions.
 */
 contract OrderGateway {
 
-    /** @dev Creates a new OrderGateway
-        @notice Creates a new OrderGateway
-    */
-    constructor() public {
-    }
-
-    /** @dev Calls participate on the provided subContract.
-        @notice Calls participate on the provided subContract.
+    /** @dev Forwards function calls of participate to the provided subContract address.
+        @notice Forwards function calls of participate to the provided subContract address.
         @param subContract Address of contract implementing the SubContract interface.
-        @param data Encoded maker values for Order encoded based on the arguments.
-        @return Boolean representing success of transaction.
+        @param data Encoded values for Order encoded in accordance to the arguments exposed by the provided subContract.
+        @return Boolean representing result of transaction.
     */
     function participate(address subContract, bytes memory data) public returns (bool) {
         return SubContract(subContract).participate(data);
     }
 
-    /** @dev Calls isValid on provided subContract.
-        @notice Calls isValid on provided subContract.
+    /** @dev Forwards function calls of isValid to the provided subContract address.
+        @notice Forwards function calls of isValid to the provided subContract address.
         @param subContract Address of contract implementing the SubContract interface.
-        @param data Encoded maker values for Order encoded based on the makerArguments.
-        @return Boolean representing the validity of makerData.
+        @param data Encoded values for Order encoded in accordance to the arguments exposed by the provided subContract.
+        @return Boolean representing the validity of data.
     */
     function isValid(address subContract, bytes memory data) public view returns (bool) {
         return SubContract(subContract).isValid(data);
     }
 
-    /** @dev Calls amountRemaining on provided subContract.
-        @notice Calls amountRemaining on provided subContract.
+    /** @dev Forwards function calls of amountRemaining to the provided subContract address.
+        @notice Forwards function calls of amountRemaining to the provided subContract address.
         @param subContract Address of contract implementing the SubContract interface.
-        @param data Encoded maker values for Order encoded based on the makerArguments.
-        @return Quantity of available asset for Order encoded in makerData.
+        @param data Encoded values for Order encoded in accordance to the arguments exposed by the provided subContract.
+        @return Quantity of available asset for Order encoded in data.
     */
     function amountRemaining(address subContract, bytes memory data) public view returns (uint) {
         return SubContract(subContract).amountRemaining(data);
     }
 
-    /** @dev Calls arguments on provided subContract.
-        @notice Calls arguments on provided subContract.
+    /** @dev Forwards function calls of arguments to the provided subContract address.
+        @notice Forwards function calls of arguments to the provided subContract address.
         @param subContract Address of contract implementing the SubContract interface.
-        @return String encoded JSON representation of subContract maker arguments.
+        @return JSON string providing expected structure of subContract input data.
     */
     function arguments(address subContract) public view returns (string memory) {
         return SubContract(subContract).arguments();

packages/kosu-system-contracts/contracts/lib/KosuToken.sol

@@ -6,7 +6,7 @@ import "./Formula.sol";
 
 /** @title KosuToken
     @author Freydal
-    @dev KosuToken (KOSU) is an implentation of the ERC-20 interface and supporting bonding curve for mints and burns.
+    @dev KosuToken (KOSU) is an implementation of the ERC-20 interface and supporting bonding curve for mints and burns.
 */
 contract KosuToken is ERC20, Authorizable {
 
@@ -16,21 +16,21 @@ contract KosuToken is ERC20, Authorizable {
     uint private _weiPaid = 0;
     uint32 constant private r = 850000; // ppm
 
-    /** @dev Deploy a new ERC20 Token
-        @notice Deploy a new ERC20 Token
+    /** @dev Initializes KosuToken with the authorizedAddresses shared permission contract to protect functions.
+        @notice Initializes KosuToken with the authorizedAddresses shared permission contract to protect functions.
     */
     constructor(address _auth) Authorizable(_auth) public {
     }
 
-    /** @dev Fallback payable method to allow contract to accept ether being sent directly to the address.
-        @notice Fallback payable method to allow contract to accept ether being sent directly to the address.
+    /** @dev Fallback payable function to allow the contract address to directly accept ether to be forwarded to the bonding function.
+        @notice Fallback payable function to allow the contract address to directly accept ether to be forwarded to the bonding function.
     */
     function () external payable {
         bondTokens(0);
     }
 
-    /** @dev Uses the ether paid to calculate and mint tokens.
-        @notice Uses the ether paid to calculate and mint tokens.
+    /** @dev Receives ether as a backing currency to be used against the bonding curve to mint tokens.
+        @notice Receives ether as a backing currency to be used against the bonding curve to mint tokens.
         @param minPayout The minimum number of tokens to mint otherwise the transaction is reverted. This should prevent a front runner modifying the output.
     */
     function bondTokens(uint minPayout) payable public returns (uint) {
@@ -45,9 +45,9 @@ contract KosuToken is ERC20, Authorizable {
         return tokensToMint;
     }
 
-    /** @dev Burns the input amount of tokens returning the calculated amount of ether.
-        @notice Burns the input amount of tokens returning the calculated amount of ether.
-        @param tokensToBurn The number of tokens to burn
+    /** @dev Burns the input tokens and releases the calculated amount of ether backing the tokens destroyed.
+        @notice Burns the input tokens and releases the calculated amount of ether backing the tokens destroyed.
+        @param tokensToBurn The number of the users tokens to burn.
     */
     function releaseTokens(uint tokensToBurn) public {
         if (tokensToBurn == 0) return;
@@ -59,50 +59,42 @@ contract KosuToken is ERC20, Authorizable {
         _weiPaid = _weiPaid.sub(etherToRelease);
     }
 
-    /** @dev Estimates the number of tokens to generate with the input ether at the current state.
-        @notice Estimates the number of tokens to generate with the input ether at the current state.
-        @param input The amount of ether to contribute
-        @return Number of tokens that would be generated
+    /** @dev Estimates the number of tokens that would be minted with the input ether at the current ether and token balances.
+        @notice Estimates the number of tokens that would be minted with the input ether at the current ether and token balances.
+        @param input The amount of ether to contribute.
+        @return Number of tokens that would be minted.
     */
     function estimateEtherToToken(uint input) public view returns (uint) {
         return calculateEtherToToken(input);
     }
 
-    /** @dev Estimates the amount of ether to return with the input number of tokens to burn.
-        @notice Estimates the amount of ether to return with the input number of tokens to burn.
-        @param input The number of tokens to burn
-        @return Amount of ether to receive
+    /** @dev Estimates the amount of ether to be released with the input number of tokens to burn.
+        @notice Estimates the amount of ether to be released with the input number of tokens to burn.
+        @param input The number of tokens to burn.
+        @return Amount of ether to release.
     */
     function estimateTokenToEther(uint input) public view returns (uint) {
         return calculateTokenToEther(input);
     }
 
-    /** @dev Burn tokens
-        @notice Burn tokens
-        @param amount Number of tokens to destroy
+    /** @dev Voluntarily burn tokens.
+        @notice Voluntarily burn tokens.
+        @param amount Number of tokens to burn.
     */
     function burn(uint amount) public isAuthorized {
         _burn(msg.sender, amount);
     }
 
-    /** @dev Mint tokens
-        @notice Mint tokens
-        @param amount Number of tokens to create
-    */
-    function mint(uint amount) public isAuthorized {
-        _mint(msg.sender, amount);
-    }
-
-    /** @dev Mint tokens to specified address
-        @notice Mint tokens to specified address
-        @param _address Address to receive tokens
-        @param amount Number of tokens to create.
+    /** @dev Authorized addresses (mostly contract systems) may manually mint new tokens to desired addresses.
+        @notice Authorized addresses (mostly contract systems) may manually mint new tokens to desired addresses.
+        @param _address Address to mint tokens to.
+        @param amount Number of tokens to mint.
     */
     function mintTo(address _address, uint amount) public isAuthorized {
         _mint(_address, amount);
     }
 
-    /** @dev Uses a modified BancorFormula to calculate the number of tokens to generate input parameters.
+    /** @dev Uses a modified BancorFormula to calculate the number of tokens to mint for input ether value.
     */
     function calculateEtherToToken(uint etherValue) internal view returns (uint) {
         if (_weiPaid == 0 && totalSupply() == 0) {
@@ -113,7 +105,7 @@ contract KosuToken is ERC20, Authorizable {
         }
     }
 
-    /** @dev Uses a modified BancorFormula to calculate the amount of ether to release with input parameters.
+    /** @dev Uses a modified BancorFormula to calculate the amount of ether to release for input token value.
     */
     function calculateTokenToEther(uint numberOfTokens) internal view returns (uint) {
         return Formula.calculateSaleReturn(totalSupply(), _weiPaid, r, numberOfTokens);