docs: update documentation

vittominacori · Oct 27, 2023 · 1e2c924 · 1e2c924
1 parent 3f13558
commit 1e2c924
Show file tree

Hide file tree

Showing 4 changed files with 78 additions and 75 deletions.
diff --git a/README.md b/README.md
@@ -5,12 +5,13 @@
 [![Coverage Status](https://codecov.io/gh/vittominacori/eth-token-recover/graph/badge.svg)](https://codecov.io/gh/vittominacori/eth-token-recover)
 [![MIT licensed](https://img.shields.io/github/license/vittominacori/eth-token-recover.svg)](https://github.com/vittominacori/eth-token-recover/blob/master/LICENSE)
 
-TokenRecover allows to recover any ERC20 or ERC721 token sent into the contract and send them to a receiver.
-
-## Motivation
+TokenRecover allows to recover any ERC20 or NFT (ERC721) token sent into the contract and send them to a receiver.
 
 There are lots of tokens lost forever into Smart Contracts (see [OMG](https://etherscan.io/address/0xd26114cd6ee289accf82350c8d8487fedb8a0c07) token balances).
-Each Ethereum contract is a potential token trap for ERC20 or ERC721 tokens. They can't be recovered, so it means money losses for end users.
+Each Ethereum contract, as well as any EVM compatible contract, is a potential token trap for ERC20 or ERC721 tokens. 
+They can't be recovered, so it means money losses for end users.
+
+By using TokenRecover, any smart contract can offer users a robust solution for reclaiming mistakenly or erroneously sent tokens, enhancing the overall user experience and confidence in the decentralized ecosystem.
 
 ## Install
 
@@ -150,9 +151,9 @@ contract MyContract is TokenRecover {
 
 ## Examples
 
-You can extend the code to add your stuff (e.g. to add custom roles or rules).
+Contracts can be extended to add custom logic (e.g. to add custom roles or rules).
 
-### Add rules to high level code
+### Add rules to high level
 
 ```solidity
 pragma solidity ^0.8.20;
@@ -177,7 +178,7 @@ contract MyContract is TokenRecover, MyDefinedRules {
 }
 ```
 
-### Add rules to low level code
+### Add rules to low level
 
 ```solidity
 pragma solidity ^0.8.20;
@@ -229,16 +230,18 @@ The v4.x (and earlier) `TokenRecover::recoverERC20` method has been updated to a
 ```
 :::
 
-If you still need a version that uses the old behavior, check the [Backwards Compatibility](#backwards-compatibility) section.
+Check the [Backwards Compatibility](#backwards-compatibility) section for additional details.
 
 ## Backwards Compatibility
 
-If you want to use a backward compatible version that
+A backward compatible (legacy) version is available in the `legacy` folder.
+
+`TokenRecoverLegacy` contract will:
 
-* implicitly sets the deployer as contract owner
-* sends recovered tokens to owner instead of providing an explicit receiver 
+* implicitly set the deployer as contract owner
+* send recovered tokens to owner instead of providing an explicit receiver 
 
-update your contracts to inherit from `TokenRecoverLegacy` contract.
+To use `TokenRecoverLegacy`, a contract inheriting from `TokenRecover` needs to be updated in the following way
 
 ```diff
 pragma solidity ^0.8.20;
@@ -255,7 +258,7 @@ pragma solidity ^0.8.20;
 ::: warning DISCLAIMER
 `TokenRecoverLegacy` is a legacy version of `TokenRecover` that works as v4.x and earlier and MAY be removed in future releases. 
 
-We highly recommend to update your code to use newer versions of the recover.
+We highly recommend to keep the code updated to use newer versions of the recover.
 :::
 
 ## Documentation

diff --git a/contracts/legacy/TokenRecoverLegacy.sol b/contracts/legacy/TokenRecoverLegacy.sol
@@ -12,8 +12,8 @@ import {RecoverERC20} from "../recover/RecoverERC20.sol";
  *
  * WARNING: The deployer address will automatically be set as contract owner.
  *
- * NOTE: this is a legacy version of Token Recover that works as v4.x and earlier and MAY be removed in future releases.
- * We highly recommend to update your code to use newer versions of the recover.
+ * NOTE: this is a legacy version of `TokenRecover` that works as v4.x and earlier and MAY be removed in future releases.
+ * We highly recommend to keep the code updated to use newer versions of the recover.
  */
 abstract contract TokenRecoverLegacy is Ownable, RecoverERC20 {
     /**

diff --git a/dist/TokenRecoverLegacy.dist.sol b/dist/TokenRecoverLegacy.dist.sol
@@ -257,8 +257,8 @@ pragma solidity ^0.8.20;
  *
  * WARNING: The deployer address will automatically be set as contract owner.
  *
- * NOTE: this is a legacy version of Token Recover that works as v4.x and earlier and MAY be removed in future releases.
- * We highly recommend to update your code to use newer versions of the recover.
+ * NOTE: this is a legacy version of `TokenRecover` that works as v4.x and earlier and MAY be removed in future releases.
+ * We highly recommend to keep the code updated to use newer versions of the recover.
  */
 abstract contract TokenRecoverLegacy is Ownable, RecoverERC20 {
     /**

diff --git a/docs/index.md b/docs/index.md
@@ -1,5 +1,63 @@
 # Solidity API
 
+## TokenRecoverLegacy
+
+_Allows the contract owner to recover any ERC20 token sent into the contract and send them to `owner()`.
+
+WARNING: The deployer address will automatically be set as contract owner.
+
+NOTE: this is a legacy version of `TokenRecover` that works as v4.x and earlier and MAY be removed in future releases.
+We highly recommend to keep the code updated to use newer versions of the recover._
+
+### constructor
+
+```solidity
+constructor() internal
+```
+
+_Initializes the contract setting the deployer as the initial owner._
+
+### recoverERC20
+
+```solidity
+function recoverERC20(address tokenAddress, uint256 tokenAmount) public virtual
+```
+
+_Recovers a `tokenAmount` of the ERC20 `tokenAddress` locked into this contract
+and sends them to the `owner()` address.
+
+NOTE: restricting access to owner only. See `RecoverERC20::_recoverERC20`._
+
+#### Parameters
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| tokenAddress | address | The contract address of the token to recover. |
+| tokenAmount | uint256 | Number of tokens to be recovered. |
+
+## RecoverERC20
+
+_Allows to recover any ERC20 token sent into the contract and send them to a receiver._
+
+### _recoverERC20
+
+```solidity
+function _recoverERC20(address tokenAddress, address tokenReceiver, uint256 tokenAmount) internal virtual
+```
+
+_Recovers a `tokenAmount` of the ERC20 `tokenAddress` locked into this contract
+and sends them to the `tokenReceiver` address.
+
+WARNING: it allows everyone to recover tokens. Access controls MUST be defined in derived contracts._
+
+#### Parameters
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| tokenAddress | address | The contract address of the token to recover. |
+| tokenReceiver | address | The address that will receive the recovered tokens. |
+| tokenAmount | uint256 | Number of tokens to be recovered. |
+
 ## ERC20Recover
 
 _Allows the contract owner to recover any ERC20 token sent into the contract and send them to a receiver._
@@ -114,29 +172,6 @@ NOTE: restricting access to owner only. See `RecoverERC721::_recoverERC721`._
 | tokenId | uint256 | The identifier for the NFT to be recovered. |
 | data | bytes | Additional data with no specified format. |
 
-## RecoverERC20
-
-_Allows to recover any ERC20 token sent into the contract and send them to a receiver._
-
-### _recoverERC20
-
-```solidity
-function _recoverERC20(address tokenAddress, address tokenReceiver, uint256 tokenAmount) internal virtual
-```
-
-_Recovers a `tokenAmount` of the ERC20 `tokenAddress` locked into this contract
-and sends them to the `tokenReceiver` address.
-
-WARNING: it allows everyone to recover tokens. Access controls MUST be defined in derived contracts._
-
-#### Parameters
-
-| Name | Type | Description |
-| ---- | ---- | ----------- |
-| tokenAddress | address | The contract address of the token to recover. |
-| tokenReceiver | address | The address that will receive the recovered tokens. |
-| tokenAmount | uint256 | Number of tokens to be recovered. |
-
 ## RecoverERC721
 
 _Allows to recover any ERC721 token sent into the contract and send them to a receiver._
@@ -161,38 +196,3 @@ WARNING: it allows everyone to recover tokens. Access controls MUST be defined i
 | tokenId | uint256 | The identifier for the NFT to be recovered. |
 | data | bytes | Additional data with no specified format. |
 
-## TokenRecoverLegacy
-
-_Allows the contract owner to recover any ERC20 token sent into the contract and send them to `owner()`.
-
-WARNING: The deployer address will automatically be set as contract owner.
-
-NOTE: this is a legacy version of Token Recover that works as v4.x and earlier and MAY be removed in future releases.
-We highly recommend to update your code to use newer versions of the recover._
-
-### constructor
-
-```solidity
-constructor() internal
-```
-
-_Initializes the contract setting the deployer as the initial owner._
-
-### recoverERC20
-
-```solidity
-function recoverERC20(address tokenAddress, uint256 tokenAmount) public virtual
-```
-
-_Recovers a `tokenAmount` of the ERC20 `tokenAddress` locked into this contract
-and sends them to the `owner()` address.
-
-NOTE: restricting access to owner only. See `RecoverERC20::_recoverERC20`._
-
-#### Parameters
-
-| Name | Type | Description |
-| ---- | ---- | ----------- |
-| tokenAddress | address | The contract address of the token to recover. |
-| tokenAmount | uint256 | Number of tokens to be recovered. |
-