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