Update eip-998.md

EIPS/eip-998.md

@@ -87,10 +87,12 @@ The `ownerOf(uint256 _tokenId)` is a standard ERC721 function. It works differen
 
 *Contracts/tokens that implement the above authentication and traversal functionality are "composable aware".*
 
-### Top-Down Composables
+### Top-Down Composable
 
 Every ERC-998 Top-Down Composable compliant contract must implement the ERC998ERC721TopDown interface and/or the ERC998ERC20TopDown interface.
 
+The ERC998ERC721TopDownEnumerable and ERC998ERC20TopDownEnumerable interfaces are optional.
+
 ```solidity
 pragma solidity ^0.4.24;
 
@@ -109,42 +111,68 @@ interface ERC998ERC721TopDown {
   event TransferChild(uint256 indexed tokenId, address indexed _to, address indexed _childContract, uint256 _childTokenId);
 
   /// @notice Get the address and parent tokenId that owns the supplied tokenId. 
-  /// @dev If _tokenId has no parent token then the first byte of isParent is 0, otherwise the first byte is 1.
-  ///  The next four bytes of isParent are the magic value 0x89885a59, which is equal to
-  ///  bytes4(keccak256(abi.encodePacked("tokenOwnerOf(uint256)")))
-  ///  If a call to tokenOwnerOf throws or the magic value is not correct then the transaction does not have to revert.
-  ///  Instead the tokenOwnerOf function is considered to not be supported by the address it was called on 
-  ///  and there is no parent token and a call to the ownerOf function should be made to get the rootOwner address.
   /// @param _tokenId The token to query for an owner address and owner token
   /// @return tokenOwner The owner address of _tokenId
   /// @return parentTokenId The parent tokenId of _tokenId
-  /// @return isParent Determines if parentTokenId is a parent tokenId and contains a magic value.
+  /// @return isParent Determines if parentTokenId is a parent tokenId and contains a magic value to ensure return values are valid.
   function tokenOwnerOf(uint256 _tokenId) external view returns (address tokenOwner, uint256 parentTokenId, uint256 isParent);
 
   /// @notice Get the parent tokenId of a child token.
-  /// @dev If the child token has no parent token then the first byte of isParent is 0, otherwise the first byte is 1.
-  ///  The next four bytes of isParent are the magic value 0xeadb80b8, which is equal to
-  ///  bytes4(keccak256(abi.encodePacked("ownerOfChild(address,uint256)")))
-  ///  If a call to ownerOfChild throws or the magic value is not correct then the transaction does not have to revert.
-  ///  Instead the ownerOfChild function is considered to not be supported by the address it was called on 
-  ///  and there is no parent token.
   /// @param _childContract The contract address of the child token.
   /// @param _childTokenId The tokenId of the child.
   /// @return parentTokenId The parent tokenId of _tokenId
-  /// @return isParent Determines if parentTokenId is a parent tokenId and contains a magic value.
+  /// @return isParent Determines if parentTokenId is a parent tokenId and contains a magic value to ensure return values are valid.
   function ownerOfChild(address _childContract, uint256 _childTokenId) external view returns (uint256 parentTokenId, uint256 isParent);
 
-
+  /// @notice A token receives a child token
+  /// @param _operator The address that caused the transfer.
+  /// @param _from The owner of the child token.
+  /// @param _childTokenId The token that is being transferred to the parent.
+  /// @param _data Up to the first 32 bytes contains an integer which is the receiving parent tokenId.  
   function onERC721Received(address _operator, address _from, uint256 _childTokenId, bytes _data) external returns(bytes4);
-  function onERC998Removed(address _operator, address _toContract, uint256 _tokenId, bytes _data) external;
+
+  /// @notice Let's an owning contract know that a specified token is transferred out
+  /// @param The address that caused the transfer.
+  /// @param _toContract The contract that receives the child token
+  /// @param _childTokenId The child tokenId that is being removed.
+  /// @param _data Additional data with no specified format
+  function onERC998Removed(address _operator, address _toContract, uint256 _childTokenId, bytes _data) external;
+
+  /// @notice Transfer child token from top-down composable to address.
+  /// @param _to The address that receives the child token
+  /// @param _childContract The ERC721 contract of the child token.
+  /// @param _childTokenId The tokenId of the token that is being transferred.
   function transferChild(address _to, address _childContract, uint256 _childTokenId) external;
+
+  /// @notice Transfer child token from top-down composable to address.
+  /// @param _to The address that receives the child token
+  /// @param _childContract The ERC721 contract of the child token.
+  /// @param _childTokenId The tokenId of the token that is being transferred.
   function safeTransferChild(address _to, address _childContract, uint256 _childTokenId) external;
+
+  /// @notice Transfer child token from top-down composable to address.
+  /// @param _to The address that receives the child token
+  /// @param _childContract The ERC721 contract of the child token.
+  /// @param _childTokenId The tokenId of the token that is being transferred.
+  /// @param _data Additional data with no specified format
   function safeTransferChild(address _to, address _childContract, uint256 _childTokenId, bytes _data) external;
-  // getChild function enables older contracts like cryptokitties to be transferred into a composable
-  // The _childContract must approve this contract. Then getChild can be called.
+
+  /// @notice Get a child token from an ERC721 contract.
+  /// @param _from The address that owns the child token.
+  /// @param _tokenId The token that becomes the parent owner
+  /// @param _childContract The ERC721 contract of the child token
+  /// @param _childTokenId The tokenId of the child token
   function getChild(address _from, uint256 _tokenId, address _childContract, uint256 _childTokenId) external;
 }
 
+###### 
+
+
+
+// getChild function enables older contracts like cryptokitties to be transferred into a composable
+  // The _childContract must approve this contract. Then getChild can be called.
+
+
 interface ERC998ERC721TopDownEnumerable {
   function totalChildContracts(uint256 _tokenId) external view returns(uint256);
   function childContractByIndex(uint256 _tokenId, uint256 _index) external view returns (address childContract);