Merge pull request #143 from 0xneves/review-natspec

docs: review of the entire NatSpec

Author: 0xneves

contracts/SwapFactory.sol

@@ -6,7 +6,7 @@ import {ISwap} from "./interfaces/ISwap.sol";
 import {ISwapFactory} from "./interfaces/ISwapFactory.sol";
 
 /**
- * @dev - SwapFactory is a helper for creating Swaps and making asset structs.
+ * @dev SwapFactory is a helper for creating Swaps and making asset structs.
  *
  * This helper can be used on and off-chain to easily create a Swap struct to be
  * used in the {Swaplace-createSwap} function.
@@ -44,7 +44,7 @@ abstract contract SwapFactory is ISwapFactory, ISwap, IErrors {
     }
 
     /**
-     *  @dev See {ISwapFactory-makeSwap}.
+     * @dev See {ISwapFactory-makeSwap}.
      */
     function makeSwap(
         address owner,

contracts/Swaplace.sol

@@ -6,15 +6,12 @@ import {ISwaplace} from "./interfaces/ISwaplace.sol";
 import {ITransfer} from "./interfaces/ITransfer.sol";
 import {SwapFactory} from "./SwapFactory.sol";
 
-/**  ___ _    ___   ___ _  _____ _   _ _
- *  | _ ) |  / _ \ / __| |/ / __| | | | |
- *  | _ \ |_| (_) | (__| ' <| _|| |_| | |__
- *  |___/____\___/ \___|_|\_\_|  \___/|____|
+/**
  * @author @0xneves | @blockful_io
- * @dev - Swaplace is a Decentralized Feeless DEX. It has no owners, it cannot be stoped.
- * Its core idea is to facilitate swaps between virtual assets following the ERC standard.
+ * @dev Swaplace is a Decentralized Feeless DEX. It has no owners, it cannot be stoped.
+ * Its cern is to facilitate swaps between virtual assets following the ERC standard.
  * Users can propose or accept swaps by allowing Swaplace to move their assets using the
- * `approve` function of the Token standard or `permit` if available.
+ * `approve` or `permit` function.
  */
 contract Swaplace is SwapFactory, ISwaplace, IERC165 {
     /// @dev Swap Identifier counter.

contracts/interfaces/ISwapFactory.sol

@@ -17,7 +17,7 @@ interface ISwapFactory {
     ) external pure returns (ISwap.Asset memory);
 
     /**
-     *  @dev Build a swap struct to use in the {Swaplace-createSwap} function.
+     * @dev Build a swap struct to use in the {Swaplace-createSwap} function.
      *
      * Requirements:
      *

contracts/mock/ERC20/ERC20.sol

@@ -19,7 +19,7 @@ abstract contract ERC20 is IERC20, IERC20Permit, IERC20Errors {
         );
 
     /**
-     *  @dev See {IERC20Permit-DOMAIN_SEPARATOR}.
+     * @dev See {IERC20Permit-DOMAIN_SEPARATOR}.
      */
     bytes32 private immutable _domainSeparator;
 
@@ -41,13 +41,12 @@ abstract contract ERC20 is IERC20, IERC20Permit, IERC20Errors {
     /**
      * @dev Map accounts to spender to the allowed transfereable value.
      */
-    mapping(address  => mapping(address  => uint256))
-        private _allowance;
+    mapping(address => mapping(address => uint256)) private _allowance;
 
     /**
      * @dev Map accounts to balance of Tokens.
      */
-    mapping(address  => uint256 ) private _balances;
+    mapping(address => uint256) private _balances;
 
     /**
      * @dev Map accounts to its current nonce.

docs/SwapFactory.md

@@ -2,31 +2,31 @@
 
 ## SwapFactory
 
-_- SwapFactory is a helper for creating Swaps and making asset structs.
+SwapFactory is a helper for creating Swaps and making asset structs.
 
 This helper can be used on and off-chain to easily create a Swap struct to be
 used in the {Swaplace-createSwap} function.
 
 Swaplace uses a {ISwap-Swap} struct to represent a Swap. This struct is
 composed of:
 
-- The `owner` of the Swap is the address that created the Swap.
-- The `allowed` address is the address that can accept the Swap. If the allowed
-  address is the zero address, then anyone can accept the Swap.
-- The `expiry` date is the timestamp that the Swap will be available to accept.
-- The `biding` are the assets that the owner is offering.
-- The `asking` are the assets that the owner wants in exchange.
+-   The `owner` of the Swap is the address that created the Swap.
+-   The `allowed` address is the address that can accept the Swap. If the allowed
+    address is the zero address, then anyone can accept the Swap.
+-   The `expiry` date is the timestamp that the Swap will be available to accept.
+-   The `biding` are the assets that the owner is offering.
+-   The `asking` are the assets that the owner wants in exchange.
 
 The Swap struct uses an {Asset} struct to represent the asset. This struct is
 composed of:
 
-- The `address` of the asset. This address can be from an ERC20 or ERC721 contract.
-- The `amount` or `id` of the asset. This amount can be the amount of ERC20 tokens
- or the id of an ERC721 token.
+-   The `address` of the asset. This address can be from an ERC20 or ERC721 contract.
+-   The `amount` or `id` of the asset. This amount can be the amount of ERC20 tokens
+    or the id of an ERC721 token.
 
 To use other standards, like ERC1155, you can wrap the ownership of the asset
 in an a trusted contract and Swap as an ERC721. This way, you can tokenize any
-on-chain execution and trade on Swaplace._
+on-chain execution and trade on Swaplace.
 
 ### makeAsset
 
@@ -42,5 +42,4 @@ _See {ISwapFactory-makeAsset}._
 function makeSwap(address owner, address allowed, uint256 expiry, struct ISwap.Asset[] biding, struct ISwap.Asset[] asking) public view virtual returns (struct ISwap.Swap)
 ```
 
-@dev See {ISwapFactory-makeSwap}.
-
+_See {ISwapFactory-makeSwap}._

docs/Swaplace.md

@@ -2,23 +2,10 @@
 
 ## Swaplace
 
-___ _    ___   ___ _  _____ _   _ _
- | _ ) |  / _ \ / __| |/ / __| | | | |
- | _ \ |_| (_) | (__| ' <| _|| |_| | |__
- |___/____\___/ \___|_|\_\_|  \___/|____|
-
-_- Swaplace is a Decentralized Feeless DEX. It has no owners, it cannot be stoped.
-Its core idea is to facilitate swaps between virtual assets following the ERC standard.
+Swaplace is a Decentralized Feeless DEX. It has no owners, it cannot be stoped.
+Its cern is to facilitate swaps between virtual assets following the ERC standard.
 Users can propose or accept swaps by allowing Swaplace to move their assets using the
-`approve` function of the Token standard or `permit` if available._
-
-### swapId
-
-```solidity
-uint256 swapId
-```
-
-_Swap Identifier counter._
+`approve` function or `permit` if available.
 
 ### createSwap
 
@@ -60,3 +47,10 @@ function supportsInterface(bytes4 interfaceID) external pure returns (bool)
 
 _See {IERC165-supportsInterface}._
 
+### totalSwaps
+
+```solidity
+function totalSwaps() public view returns (uint256)
+```
+
+_Getter function for \_totalSwaps._

docs/echidna/TestSwapFactory.md

@@ -0,0 +1,34 @@
+# Solidity API
+
+## TestFactory
+
+### has_values
+
+```solidity
+function has_values() public
+```
+
+### make_asset_array
+
+```solidity
+function make_asset_array(address addr, uint256 amountOrId) public pure returns (struct ISwap.Asset[])
+```
+
+### make_valid_swap
+
+```solidity
+function make_valid_swap(address owner, address addr, uint256 amountOrId) public view returns (struct ISwap.Swap)
+```
+
+### echidna_revert_invalid_expiry
+
+```solidity
+function echidna_revert_invalid_expiry() public view
+```
+
+### echidna_revert_invalid_length
+
+```solidity
+function echidna_revert_invalid_length() public view
+```
+

docs/echidna/TestSwaplace.md

@@ -0,0 +1,34 @@
+# Solidity API
+
+## TestSwaplace
+
+### constructor
+
+```solidity
+constructor() public
+```
+
+### echidna_create_swap
+
+```solidity
+function echidna_create_swap() public returns (bool)
+```
+
+### echidna_accept_swap
+
+```solidity
+function echidna_accept_swap() public returns (bool)
+```
+
+### echidna_id_overflow
+
+```solidity
+function echidna_id_overflow() public view returns (bool)
+```
+
+### echidna_id_never_zero_after_init
+
+```solidity
+function echidna_id_never_zero_after_init() public view returns (bool)
+```
+

docs/interfaces/IERC165.md

@@ -2,24 +2,23 @@
 
 ## IERC165
 
-_Interface of the ERC165 standard, as defined in the
+Interface of the ERC165 standard, as defined in the
 https://eips.ethereum.org/EIPS/eip-165[EIP].
 
 Implementers can declare support of contract interfaces, which can then be
 queried by others ({ERC165Checker}).
 
-For an implementation, see {ERC165}._
+For an implementation, see {ERC165}.
 
 ### supportsInterface
 
 ```solidity
 function supportsInterface(bytes4 interfaceId) external view returns (bool)
 ```
 
-_Returns true if this contract implements the interface defined by
+Returns true if this contract implements the interface defined by
 `interfaceId`. See the corresponding
 https://eips.ethereum.org/EIPS/eip-165#how-interfaces-are-identified[EIP section]
 to learn more about how these ids are created.
 
-This function call must use less than 30 000 gas._
-
+This function call must use less than 30 000 gas.

docs/interfaces/IErrors.md

@@ -2,34 +2,33 @@
 
 ## IErrors
 
-_Errors only interface for the {Swaplace} implementations._
+Errors only interface for the {Swaplace} implementations.
 
 ### InvalidAddress
 
 ```solidity
 error InvalidAddress(address caller)
 ```
 
-_Displayed when the caller is not the owner of the swap._
+Displayed when the caller is not the owner of the swap.
 
 ### InvalidAssetsLength
 
 ```solidity
 error InvalidAssetsLength()
 ```
 
-_Displayed when the amount of {ISwap-Asset} has a length of zero.
+Displayed when the amount of {ISwap-Asset} has a length of zero.
 
 NOTE: The `biding` or `asking` array must not be empty to avoid mistakes
 when creating a swap. Assuming one side of the swap is empty, the
 correct approach should be the usage of {transferFrom} and we reinforce
-this behavior by requiring the length of the array to be bigger than zero._
+this behavior by requiring the length of the array to be bigger than zero.
 
 ### InvalidExpiry
 
 ```solidity
 error InvalidExpiry(uint256 timestamp)
 ```
 
-_Displayed when the `expiry` date is in the past._
-
+Displayed when the `expiry` date is in the past.

docs/interfaces/ISwap.md

@@ -2,7 +2,7 @@
 
 ## ISwap
 
-_Interface for the Swap Struct, used in the {Swaplace} implementation._
+Interface for the Swap Struct, used in the {Swaplace} implementation.
 
 ### Asset
 
@@ -13,6 +13,15 @@ struct Asset {
 }
 ```
 
+Assets can be ERC20 or ERC721.
+
+It is composed of:
+
+-   `addr` of the asset.
+-   `amountOrId` of the asset based on the standard.
+
+NOTE: `amountOrId` is the `amount` of ERC20 or the `tokenId` of ERC721.
+
 ### Swap
 
 ```solidity
@@ -25,3 +34,14 @@ struct Swap {
 }
 ```
 
+The Swap struct is the heart of Swaplace.
+
+It is composed of:
+
+-   `owner` of the Swap.
+-   `allowed` address to accept the Swap.
+-   `expiry` date of the Swap.
+-   `biding` assets that are being bided by the owner.
+-   `asking` assets that are being asked by the owner.
+
+NOTE: When `allowed` address is the zero address, anyone can accept the Swap.

docs/interfaces/ISwapFactory.md

@@ -2,27 +2,26 @@
 
 ## ISwapFactory
 
-_Interface of the {SwapFactory} implementation._
+Interface of the {SwapFactory} implementation.
 
 ### makeAsset
 
 ```solidity
 function makeAsset(address addr, uint256 amountOrId) external pure returns (struct ISwap.Asset)
 ```
 
-_Constructs an asset struct that works for ERC20 or ERC721.
-This function is a utility to easily create an `Asset` struct on-chain or off-chain._
+Constructs an asset struct that works for ERC20 or ERC721.
+This function is a utility to easily create an `Asset` struct on-chain or off-chain.
 
 ### makeSwap
 
 ```solidity
 function makeSwap(address owner, address allowed, uint256 expiry, struct ISwap.Asset[] assets, struct ISwap.Asset[] asking) external view returns (struct ISwap.Swap)
 ```
 
-@dev Build a swap struct to use in the {Swaplace-createSwap} function.
+Build a swap struct to use in the {Swaplace-createSwap} function.
 
 Requirements:
 
-- `expiry` cannot be in the past timestamp.
-- `biding` and `asking` cannot be empty.
-
+-   `expiry` cannot be in the past timestamp.
+-   `biding` and `asking` cannot be empty.