Merge pull request #146 from PolymathNetwork/natspec

Improved Natspec Comments

contracts/ModuleRegistry.sol

@@ -7,11 +7,9 @@ import "./interfaces/ISecurityTokenRegistry.sol";
 import "./Registry.sol";
 
 /**
-* @title ModuleRegistry
-* @notice Stores registered modules
-* Anyone can register modules, but only those "approved" by Polymath will be allowed to everyone.
+* @title Registry contract to store registered modules
+* @notice Anyone can register modules, but only those "approved" by Polymath will be available for issuers to add
 */
-
 contract ModuleRegistry is IModuleRegistry, Registry {
 
     // Mapping used to hold the type of module factory corresponds to the address of the Module factory contract
@@ -33,7 +31,7 @@ contract ModuleRegistry is IModuleRegistry, Registry {
     event LogModuleVerified(address indexed _moduleFactory, bool _verified);
 
     /**
-    * @dev Called by a security token to notify the registry it is using a module
+    * @notice Called by a security token to notify the registry it is using a module
     * @param _moduleFactory is the address of the relevant module factory
     */
     function useModule(address _moduleFactory) external {
@@ -49,8 +47,9 @@ contract ModuleRegistry is IModuleRegistry, Registry {
     }
 
     /**
-    * @dev Called by moduleFactory owner to register new modules for SecurityToken to use
+    * @notice Called by moduleFactory owner to register new modules for SecurityToken to use
     * @param _moduleFactory is the address of the module factory to be registered
+    * @return bool
     */
     function registerModule(address _moduleFactory) external whenNotPaused returns(bool) {
         require(registry[_moduleFactory] == 0, "Module factory should not be pre-registered");
@@ -64,10 +63,11 @@ contract ModuleRegistry is IModuleRegistry, Registry {
     }
 
     /**
-    * @dev Called by Polymath to verify modules for SecurityToken to use.
-    * A module can not be used by an ST unless first approved/verified by Polymath
-    * (The only exception to this is that the author of the module is the owner of the ST)
+    * @notice Called by Polymath to verify modules for SecurityToken to use.
+    * @notice A module can not be used by an ST unless first approved/verified by Polymath
+    * @notice (The only exception to this is that the author of the module is the owner of the ST)
     * @param _moduleFactory is the address of the module factory to be registered
+    * @return bool
     */
     function verifyModule(address _moduleFactory, bool _verified) external onlyOwner returns(bool) {
         //Must already have been registered
@@ -78,15 +78,16 @@ contract ModuleRegistry is IModuleRegistry, Registry {
     }
 
     /**
-     * @dev Use to get all the tags releated to the functionality of the Module Factory.
+     * @notice Use to get all the tags releated to the functionality of the Module Factory.
      * @param _moduleType Type of module
+     * @return bytes32 array
      */
     function getTagByModuleType(uint8 _moduleType) public view returns(bytes32[]) {
         return availableTags[_moduleType];
     }
 
     /**
-     * @dev Add the tag for specified Module Factory
+     * @notice Add the tag for specified Module Factory
      * @param _moduleType Type of module.
      * @param _tag List of tags
      */
@@ -97,7 +98,7 @@ contract ModuleRegistry is IModuleRegistry, Registry {
      }
 
     /**
-     * @dev remove the tag for specified Module Factory
+     * @notice remove the tag for specified Module Factory
      * @param _moduleType Type of module.
      * @param _removedTags List of tags
      */

contracts/Pausable.sol

@@ -1,5 +1,8 @@
 pragma solidity ^0.4.23;
 
+/**
+ * @title Utility contract to allow pausing and unpausing of certain functions
+ */
 contract Pausable {
 
     event Pause(uint256 _timestammp);
@@ -8,23 +11,23 @@ contract Pausable {
     bool public paused = false;
 
     /**
-    * @dev Modifier to make a function callable only when the contract is not paused.
+    * @notice Modifier to make a function callable only when the contract is not paused.
     */
     modifier whenNotPaused() {
         require(!paused);
         _;
     }
 
     /**
-    * @dev Modifier to make a function callable only when the contract is paused.
+    * @notice Modifier to make a function callable only when the contract is paused.
     */
     modifier whenPaused() {
         require(paused);
         _;
     }
 
    /**
-    * @dev called by the owner to pause, triggers stopped state
+    * @notice called by the owner to pause, triggers stopped state
     */
     function _pause() internal {
         require(!paused);
@@ -33,7 +36,7 @@ contract Pausable {
     }
 
     /**
-    * @dev called by the owner to unpause, returns to normal state
+    * @notice called by the owner to unpause, returns to normal state
     */
     function _unpause() internal {
         require(paused);

contracts/ReclaimTokens.sol

@@ -3,10 +3,13 @@ pragma solidity ^0.4.23;
 import "openzeppelin-solidity/contracts/ownership/Ownable.sol";
 import "openzeppelin-solidity/contracts/token/ERC20/ERC20Basic.sol";
 
+/**
+ * @title Utility contract to allow owner to retreive any ERC20 sent to the contract
+ */
 contract ReclaimTokens is Ownable {
 
     /**
-    * @dev Reclaim all ERC20Basic compatible tokens
+    * @notice Reclaim all ERC20Basic compatible tokens
     * @param _tokenContract The address of the token contract
     */
     function reclaimERC20(address _tokenContract) external onlyOwner {

contracts/Registry.sol

@@ -4,6 +4,9 @@ import "./Pausable.sol";
 import "./ReclaimTokens.sol";
 import "./interfaces/IRegistry.sol";
 
+/**
+ * @title Core functionality for registry upgradability
+ */
 contract Registry is IRegistry, Pausable, ReclaimTokens {
 
     /*
@@ -20,16 +23,17 @@ contract Registry is IRegistry, Pausable, ReclaimTokens {
     event LogChangeAddress(string _nameKey, address indexed _oldAddress, address indexed _newAddress);
 
     /**
-     * @dev get the contract address
+     * @notice Get the contract address
      * @param _nameKey is the key for the contract address mapping
+     * @return address
      */
     function getAddress(string _nameKey) view public returns(address) {
         require(validAddressKeys[keccak256(_nameKey)]);
         return storedAddresses[keccak256(_nameKey)];
     }
 
     /**
-     * @dev change the contract address
+     * @notice change the contract address
      * @param _nameKey is the key for the contract address mapping
      * @param _newAddress is the new contract address
      */
@@ -45,14 +49,14 @@ contract Registry is IRegistry, Pausable, ReclaimTokens {
     }
 
     /**
-     * @dev pause (overridden function)
+     * @notice pause registration function
      */
     function unpause() public onlyOwner  {
         super._unpause();
     }
 
     /**
-     * @dev unpause (overridden function)
+     * @notice unpause registration function
      */
     function pause() public onlyOwner {
         super._pause();

contracts/SecurityTokenRegistry.sol

@@ -7,6 +7,9 @@ import "./interfaces/ISecurityTokenRegistry.sol";
 import "./Registry.sol";
 import "./helpers/Util.sol";
 
+/**
+ * @title Registry contract for issuers to register their security tokens
+ */
 contract SecurityTokenRegistry is ISecurityTokenRegistry, Util, Registry {
 
     // Registration fee in POLY base 18 decimals
@@ -18,10 +21,6 @@ contract SecurityTokenRegistry is ISecurityTokenRegistry, Util, Registry {
     event LogNewSecurityToken(string _ticker, address indexed _securityTokenAddress, address _owner);
     event LogAddCustomSecurityToken(string _name, string _symbol, address _securityToken, uint256 _addedAt);
 
-     /**
-     * @dev Constructor used to set the essentials addresses to facilitate
-     * the creation of the security token
-     */
     constructor (
         address _polyToken,
         address _moduleRegistry,
@@ -41,10 +40,11 @@ contract SecurityTokenRegistry is ISecurityTokenRegistry, Util, Registry {
     }
 
     /**
-     * @dev Creates a new Security Token and saves it to the registry
+     * @notice Creates a new Security Token and saves it to the registry
      * @param _name Name of the token
      * @param _symbol Ticker symbol of the security token
      * @param _tokenDetails off-chain details of the token
+     * @param _divisible Set to true if token is divisible
      */
     function generateSecurityToken(string _name, string _symbol, string _tokenDetails, bool _divisible) public whenNotPaused {
         require(bytes(_name).length > 0 && bytes(_symbol).length > 0, "Name and Symbol string length should be greater than 0");
@@ -67,7 +67,7 @@ contract SecurityTokenRegistry is ISecurityTokenRegistry, Util, Registry {
     }
 
     /**
-     * @dev Add a new custom (Token should follow the ISecurityToken interface) Security Token and saves it to the registry
+     * @notice Add a new custom (Token should follow the ISecurityToken interface) Security Token and saves it to the registry
      * @param _name Name of the token
      * @param _symbol Ticker symbol of the security token
      * @param _owner Owner of the token
@@ -86,9 +86,9 @@ contract SecurityTokenRegistry is ISecurityTokenRegistry, Util, Registry {
     }
 
     /**
-    * @dev Changes the protocol version and the SecurityToken contract that the registry points to
-    * Used only by Polymath to upgrade the SecurityToken contract and add more functionalities to future versions
-    * Changing versions does not affect existing tokens.
+    * @notice Changes the protocol version and the SecurityToken contract
+    * @notice Used only by Polymath to upgrade the SecurityToken contract and add more functionalities to future versions
+    * @notice Changing versions does not affect existing tokens.
     */
     function setProtocolVersion(address _stVersionProxyAddress, bytes32 _version) public onlyOwner {
         protocolVersion = _version;
@@ -99,19 +99,21 @@ contract SecurityTokenRegistry is ISecurityTokenRegistry, Util, Registry {
     ///////// Get Functions
     //////////////////////////////
     /**
-     * @dev Get security token address by ticker name
+     * @notice Get security token address by ticker name
      * @param _symbol Symbol of the Scurity token
-     * @return address _symbol
+     * @return address
      */
     function getSecurityTokenAddress(string _symbol) public view returns (address) {
         string memory __symbol = upper(_symbol);
         return symbols[__symbol];
     }
 
      /**
-     * @dev Get security token data by its address
+     * @notice Get security token data by its address
      * @param _securityToken Address of the Scurity token
-     * @return string, address, string
+     * @return string
+     * @return address
+     * @return string
      */
     function getSecurityTokenData(address _securityToken) public view returns (string, address, string) {
         return (
@@ -122,7 +124,7 @@ contract SecurityTokenRegistry is ISecurityTokenRegistry, Util, Registry {
     }
 
     /**
-    * @dev Check that Security Token is registered
+    * @notice Check that Security Token is registered
     * @param _securityToken Address of the Scurity token
     * @return bool
     */
@@ -131,7 +133,7 @@ contract SecurityTokenRegistry is ISecurityTokenRegistry, Util, Registry {
     }
 
     /**
-     * @dev set the ticker registration fee in POLY tokens
+     * @notice set the ticker registration fee in POLY tokens
      * @param _registrationFee registration fee in POLY tokens (base 18 decimals)
      */
     function changePolyRegisterationFee(uint256 _registrationFee) public onlyOwner {

contracts/TickerRegistry.sol

@@ -1,22 +1,16 @@
 pragma solidity ^0.4.23;
 
-/*
-  Allows issuers to reserve their token symbols ahead of actually generating their security token.
-  SecurityTokenRegistry would reference this contract and ensure that a token symbol exists here and
-  only its owner can deploy the token with that symbol.
-*/
-
 import "openzeppelin-solidity/contracts/math/SafeMath.sol";
 import "openzeppelin-solidity/contracts/token/ERC20/ERC20.sol";
 import "./interfaces/ITickerRegistry.sol";
 import "./Registry.sol";
 import "./helpers/Util.sol";
 
 /**
- * @title TickerRegistry
- * @dev Contract used to register the security token symbols
+ * @title Registry contract for issuers to reserve their security token symbols
+ * @notice Allows issuers to reserve their token symbols ahead of actually generating their security token.
+ * @dev SecurityTokenRegistry would reference this contract and ensure that a token symbol exists here and only its owner can deploy the token with that symbol.
  */
-
 contract TickerRegistry is ITickerRegistry, Util, Registry {
 
     using SafeMath for uint256;
@@ -52,9 +46,9 @@ contract TickerRegistry is ITickerRegistry, Util, Registry {
     }
 
     /**
-     * @dev Register the token symbol for its particular owner
-            Once the token symbol is registered to its owner then no other issuer can claim
-            its ownership. If the symbol expires and its issuer hasn't used it, then someone else can take it.
+     * @notice Register the token symbol for its particular owner
+     * @notice Once the token symbol is registered to its owner then no other issuer can claim
+     * @notice its ownership. If the symbol expires and its issuer hasn't used it, then someone else can take it.
      * @param _symbol token symbol
      * @param _tokenName Name of the token
      * @param _owner Address of the owner of the token
@@ -70,10 +64,10 @@ contract TickerRegistry is ITickerRegistry, Util, Registry {
         emit LogRegisterTicker (_owner, symbol, _tokenName, _swarmHash, now);
     }
 
-     /**
-      * @dev Change the expiry time for the token symbol
-      * @param _newExpiry new time period for token symbol expiry
-      */
+    /**
+     * @notice Change the expiry time for the token symbol
+     * @param _newExpiry new time period for token symbol expiry
+     */
     function changeExpiryLimit(uint256 _newExpiry) public onlyOwner {
         require(_newExpiry >= 1 days, "Expiry should greater than or equal to 1 day");
         uint256 _oldExpiry = expiryLimit;
@@ -82,7 +76,7 @@ contract TickerRegistry is ITickerRegistry, Util, Registry {
     }
 
     /**
-     * @dev Check the validity of the symbol
+     * @notice Check the validity of the symbol
      * @param _symbol token symbol
      * @param _owner address of the owner
      * @param _tokenName Name of the token
@@ -100,7 +94,7 @@ contract TickerRegistry is ITickerRegistry, Util, Registry {
     }
 
     /**
-     * @dev Check the symbol is reserved or not
+     * @notice Check the symbol is reserved or not
      * @param _symbol Symbol of the token
      * @param _owner Owner of the token
      * @param _tokenName Name of the token
@@ -123,8 +117,13 @@ contract TickerRegistry is ITickerRegistry, Util, Registry {
      }
 
     /**
-     * @dev Returns the owner and timestamp for a given symbol
+     * @notice Returns the owner and timestamp for a given symbol
      * @param _symbol symbol
+     * @return address
+     * @return uint256
+     * @return string
+     * @return bytes32
+     * @return bool
      */
     function getDetails(string _symbol) public view returns (address, uint256, string, bytes32, bool) {
         string memory symbol = upper(_symbol);
@@ -142,8 +141,9 @@ contract TickerRegistry is ITickerRegistry, Util, Registry {
     }
 
     /**
-     * @dev To re-initialize the token symbol details if symbol validity expires
+     * @notice To re-initialize the token symbol details if symbol validity expires
      * @param _symbol token symbol
+     * @return bool
      */
     function expiryCheck(string _symbol) internal returns(bool) {
         if (registeredSymbols[_symbol].owner != address(0)) {
@@ -157,7 +157,7 @@ contract TickerRegistry is ITickerRegistry, Util, Registry {
     }
 
     /**
-     * @dev set the ticker registration fee in POLY tokens
+     * @notice set the ticker registration fee in POLY tokens
      * @param _registrationFee registration fee in POLY tokens (base 18 decimals)
      */
     function changePolyRegisterationFee(uint256 _registrationFee) public onlyOwner {