Adds inline documentation for the contracts

contracts/KernelInstance.sol

@@ -2,10 +2,22 @@ pragma solidity ^0.4.21;
 
 import "zeppelin-solidity/contracts/ownership/Ownable.sol";
 
+/**
+ * @title KernelInstance
+ * @dev This contract represents a particular Kernel version from a distribution. Has an immutable reference to all contract implementations that comprise this version.
+ */
 contract KernelInstance is Ownable {
+
+  // Distribution name
   string public name;
+
+  // Distribution version
   string public version;
+
+  // Developer address to which staking payouts will be sent
   address public developer;
+
+  // Parent KernelInstance in the version tree, acts as a fallback for missing implementations
   KernelInstance public parent;
 
   // Provides freezing behavior to prevent implementations defined in parent to be overwritten
@@ -14,13 +26,27 @@ contract KernelInstance is Ownable {
   // Mapping from a contract name to its implementation address
   mapping(string => address) private implementations;
 
+  /**
+   * @dev Event signaling that a new implementation for a contract has been added
+   * @param contractName representing the name of the contract
+   * @param implementation representing the address of the implementation
+   */
   event ImplementationAdded(string contractName, address implementation);
 
+  /**
+  * @dev Guarantees the KernelInstance is not frozen
+  */
   modifier notFrozen() {
     require(!frozen);
     _;
   }
 
+  /**
+   * @dev Constructor function that sets the distribution's name, version, developer and parent while checking the latter is frozen
+   * @param _name representing the name of the distribution
+   * @param _version representing the version of the distribution
+   * @param _parent representing the parent KernelInstance in the version tree
+   */
   function KernelInstance(string _name, string _version, KernelInstance _parent) public {
     if(_parent != address(0)) { require(_parent.frozen()); }
     name = _name;
@@ -29,24 +55,41 @@ contract KernelInstance is Ownable {
     developer = msg.sender;
   }
 
+  /**
+   * @dev Retrieves the hash representing the KernelInstance
+   * @return the hash representing the KernelInstance
+   */
   function getHash() public view returns(bytes32) {
     return keccak256(name, version);
   }
 
+  /**
+   * @dev Adds an implementation for a contract to the KernelInstance and emits the corresponding event
+   * @param contractName representing the name of the contract
+   * @param implementation representing the address of the implementation
+   */
   function addImplementation(string contractName, address implementation) onlyOwner notFrozen public {
     require(implementation != address(0));
     require(implementations[contractName] == address(0));
     implementations[contractName] = implementation;
     emit ImplementationAdded(contractName, implementation);
   }
 
+  /**
+   * @dev Retrieves the implementation address for a given contract
+   * @param contractName representing the name of the contract
+   * @return the implementation address or 0 if it does not exist
+   */
   function getImplementation(string contractName) public view returns(address) {
     address implementation = implementations[contractName];
     if(implementation != address(0)) return implementation;
     else if(parent != address(0)) return parent.getImplementation(contractName); 
     else return 0;
   }
 
+  /**
+   * @dev Locks the KernelInstance to avoid adding new implementations
+   */
   function freeze() onlyOwner notFrozen public {
     frozen = true;
   }

contracts/KernelRegistry.sol

@@ -4,22 +4,47 @@ import "./KernelInstance.sol";
 import "zos-core/contracts/Initializable.sol";
 import "zeppelin-solidity/contracts/ownership/Ownable.sol";
 
+/**
+ * @title KernelRegistry
+ * @dev This contract keeps track of all submitted Kernel versions
+ */
 contract KernelRegistry is Initializable, Ownable {
+  /**
+   * @dev Event signaling that a new instance has been registered
+   * @param instance representing the new KernelInstance
+   */
   event NewInstance(KernelInstance indexed instance);
 
+  // Mapping from a kernel's hash to its address
   mapping(bytes32 => address) private instances;
 
+  /**
+  * @dev Constructor function
+  */
   function KernelRegistry() public {}
 
+  /**
+   * @dev Initialization function, sets the owner of the registry
+   * @param _owner representing the address of the owner
+   */
   function initialize(address _owner) public isInitializer {
     owner = _owner;
   }
 
+  /**
+   * @dev Retrieves the kernel for a version of a given distribution
+   * @param name representing the distribution
+   * @param version representing the distribution's version
+   */
   function getInstance(string name, string version) public view returns (KernelInstance) {
     bytes32 hash = keccak256(name, version);
     return KernelInstance(instances[hash]);
   }
 
+  /**
+   * @dev Registers a new kernel version and emits the corresponding event
+   * @param _instance representing the kernel to be registered
+   */
   function addInstance(KernelInstance _instance) onlyOwner public {
     bytes32 hash = _instance.getHash();
     require(instances[hash] == address(0));
@@ -28,6 +53,10 @@ contract KernelRegistry is Initializable, Ownable {
     emit NewInstance(_instance);
   }
 
+  /**
+   * @dev Retrieves whether a given kernel has been registered
+   * @param _instance representing the kernel
+   */
   function isRegistered(KernelInstance _instance) public view returns (bool) {
     bytes32 hash = _instance.getHash();
     return instances[hash] != address(0);

contracts/KernelStakes.sol

@@ -1,38 +1,93 @@
 pragma solidity ^0.4.21;
 
-import "./ZepToken.sol";
 import "zos-core/contracts/Initializable.sol";
 import "zeppelin-solidity/contracts/math/SafeMath.sol";
 import "zeppelin-solidity/contracts/ownership/Ownable.sol";
 
+
+/**
+ * @title KernelStakes
+ * @dev This contract keeps track of all submitted stakes for kernel instances
+ */
 contract KernelStakes is Initializable, Ownable {
   using SafeMath for uint256;
 
+  /**
+   * @dev Event signaling a new staking
+   * @param staker representing the address of the staker
+   * @param instance representing the kernel staked for
+   * @param amount representing the staked amount
+   * @param total representing the new total amount staked by the staker
+   * @param data representing additional information for complex staking models
+   */
   event Staked(address indexed staker, address instance, uint256 amount, uint256 total, bytes data);
+
+  /**
+   * @dev Event signaling an unstaking
+   * @param staker representing the address of the staker
+   * @param instance representing the kernel unstaked for
+   * @param amount representing the unstaked amount
+   * @param total representing the new total amount staked by the staker
+   * @param data representing additional information for complex staking models
+   */
   event Unstaked(address indexed staker, address instance, uint256 amount, uint256 total, bytes data);
 
+  // Total amount of staked tokens
   uint256 private _totalStaked;
+
+  // Mapping from a kernel address to its staked amount
   mapping(address => uint256) private _instanceVouches;
+
+  // Mapping of staker addresses to their staked amount for a given kernel address
   mapping(address => mapping (address => uint256)) private _stakerVouches;
 
+  /**
+  * @dev Constructor function
+  */
   function KernelStakes() public {}
 
+  /**
+   * @dev Initialization function, sets the owner
+   * @param _owner representing the address of the owner
+   */
   function initialize(address _owner) public isInitializer {
     owner = _owner;
   }
 
+  /**
+   * @dev Retrieves the total staked amount
+   * @return the total staked amount
+   */
   function totalStaked() public view returns (uint256) {
     return _totalStaked;
   }
 
+  /**
+   * @dev Retrieves the staked amount for a given kernel
+   * @param instance representing the kernel instance
+   * @return the total staked amount for a given kernel
+   */
   function totalStakedFor(address instance) public view returns (uint256) {
     return _instanceVouches[instance];
   }
 
+  /**
+   * @dev Retrieves the staked amount by a staker for a given kernel
+   * @param staker representing the staker address
+   * @param instance representing the kernel instance
+   * @return the total staked amount by the staker for the given kernel
+   */
   function stakedFor(address staker, address instance) public view returns (uint256) {
     return _stakerVouches[staker][instance];
   }
 
+  /**
+   * @dev Stakes a given amount for a given kernel instance and emits the corresponding event
+   * @param staker representing the staker address
+   * @param instance representing the kernel instance being staked for
+   * @param amount representing the amount being staked
+   * @param data representing additional information for complex staking models
+   */
   function stake(address staker, address instance, uint256 amount, bytes data) public onlyOwner {
     _totalStaked = _totalStaked.add(amount);
     _instanceVouches[instance] = _instanceVouches[instance].add(amount);
@@ -41,6 +96,13 @@ contract KernelStakes is Initializable, Ownable {
     emit Staked(staker, instance, amount, _instanceVouches[instance], data);
   }
 
+  /**
+   * @dev Unstakes a given amount for a given kernel instance and emits the corresponding event
+   * @param staker representing the staker address
+   * @param instance representing the kernel instance being unstaked for
+   * @param amount representing the amount being unstaked
+   * @param data representing additional information for complex staking models
+   */
   function unstake(address staker, address instance, uint256 amount, bytes data) public onlyOwner {
     uint256 currentStake = _stakerVouches[staker][instance];
     require(currentStake >= amount);

contracts/ZepCore.sol

@@ -11,23 +11,49 @@ import "zos-core/contracts/upgradeability/UpgradeabilityProxyFactory.sol";
 import "zos-core/contracts/ImplementationProvider.sol";
 import "zeppelin-solidity/contracts/math/SafeMath.sol";
 
+/**
+ * @title ZepCore
+ * @dev This contract controls the kernel distributions and versions for ZeppelinOS
+ */
 contract ZepCore is Initializable, ImplementationProvider {
   using SafeMath for uint256;
 
+  // Token used for staking
   ZepToken private _token;
+
+  // Registry of kernel versions
   KernelRegistry private _registry;
+
+  // Staking contract
   KernelStakes private _stakes;
 
+  // Price of registering a new kernel version
   uint256 public newVersionCost;
+
+  // Fraction of stakes rewarded to the developer of a kernel instance
   uint256 public developerFraction;
 
+  /**
+  * @dev Guarantees that a given kernel instance is registered
+  */
   modifier isRegistered(KernelInstance instance) {
     require(_registry.isRegistered(instance));
     _;
   }
 
+  /**
+  * @dev Constructor function
+  */
   function ZepCore() public {}
 
+  /**
+   * @dev Initialization function
+   * @param newVersionCost_ representing the price of registering a kernel version
+   * @param developerFraction_ representing the fraction of stakes rewarded to the developer of a kernel instance
+   * @param token_ representing the address of the staking token
+   * @param registry_ representing the versions registry contract
+   * @param stakes_ representing the address of staking contract
+   */
   function initialize(
     uint256 newVersionCost_,
     uint256 developerFraction_,
@@ -43,18 +69,34 @@ contract ZepCore is Initializable, ImplementationProvider {
     // TODO: we need to think how we are going to manage variable costs to propose new versions
   }
 
+  /**
+   * @dev Retrieves the token used for staking
+   * @return the token used for staking
+   */
   function token() public view returns (ZepToken) {
     return _token;
   }
 
+  /**
+   * @dev Retrieves the registry of kernel versions
+   * @return the registry of kernel versions
+   */
   function registry() public view returns (KernelRegistry) {
     return _registry;
   }
 
+  /**
+   * @dev Retrieves the staking contract
+   * @return the staking contract
+   */
   function stakes() public view returns (KernelStakes) {
     return _stakes;
   }
 
+  /**
+   * @dev Registers a new kernel instance into the registry and burns the sender's required amount of tokens for it
+   * @param instance representing the kernel instance to be registered
+   */
   function register(KernelInstance instance) public {
     _registry.addInstance(instance);
 
@@ -63,30 +105,70 @@ contract ZepCore is Initializable, ImplementationProvider {
     _token.burn(newVersionCost);
   }
 
+  /**
+   * @dev Retrieves the kernel instance for a given distribution name and version
+   * @param name representing the distribution name
+   * @param version representing the distribution version
+   * @return the kernel instance
+   */
   function getInstance(string name, string version) public view returns(KernelInstance) {
     return _registry.getInstance(name, version);
   }
 
+  /**
+   * @dev Retrieves the implementation of a contract for a given distribution and version
+   * @param distribution representing the distribution name
+   * @param version representing the distribution version
+   * @param contractName representing the contract name
+   * @return the implementation address
+   */
   function getImplementation(string distribution, string version, string contractName) public view returns (address) {
     KernelInstance instance = getInstance(distribution, version);
     return instance.getImplementation(contractName);
   }
 
+  /**
+   * @dev Stakes a given amount for a given kernel instance
+   * @param instance representing the kernel instance being staked for
+   * @param amount representing the amount being staked
+   * @param data representing additional information for complex staking models
+   */
   function stake(KernelInstance instance, uint256 amount, bytes data) public isRegistered(instance) {
     _token.transferFrom(msg.sender, this, amount);
     _payoutAndStake(msg.sender, instance, amount, data);
   }
 
-  function unstake(KernelInstance instance, uint256 amount, bytes data) public isRegistered(instance) {
+  /**
+   * @dev Unstakes a given amount for a given kernel instance
+   * @param instance representing the kernel instance being unstaked for
+   * @param amount representing the amount being unstaked
+   * @param data representing additional information for complex staking models
+   */
+  function unstake(KernelInstance instance, uint256 amount, bytes data) public isRegistered(instance) { 
     _stakes.unstake(msg.sender, instance, amount, data);
     _token.transfer(msg.sender, amount);
   }
 
+  /**
+   * @dev Transfers stakes from a kernel instance to another one
+   * @param from representing the kernel instance being unstaked for
+   * @param to representing the kernel instance being staked for
+   * @param amount representing the amount of stakes being transferred
+   * @param data representing additional information for complex staking models
+   */
   function transferStake(KernelInstance from, KernelInstance to, uint256 amount, bytes data) public isRegistered(from) isRegistered(to) {
     _stakes.unstake(msg.sender, from, amount, data);
     _payoutAndStake(msg.sender, to, amount, data);
   }
 
+  /**
+   * @dev Stakes tokens for a given instance and pays the corresponding fraction to its developer
+   * @param staker representing the address of the staker
+   * @param instance representing the kernel instance being staked for
+   * @param amount representing the amount being staked
+   * @param data representing additional information for complex staking models
+
+   */
   function _payoutAndStake(address staker, KernelInstance instance, uint256 amount, bytes data) internal {
     uint256 developerPayout = amount.div(developerFraction);
     require(developerPayout > 0);