fix: MUD 272 - Update NatSpec, Generate Docs (#40)

README.md

@@ -3,3 +3,7 @@
 [![CircleCI](https://dl.circleci.com/status-badge/img/gh/zer0-os/zNS/tree/development.svg?style=svg)](https://dl.circleci.com/status-badge/redirect/gh/zer0-os/zNS/tree/development)
 
 # zNS
+
+### [System Architecture](./docs/architecture.md)
+### [Smart Contract Docs](./docs/contracts)
+### [Flow Diagrams](./docs/flows.md)

contracts/access/AccessControlled.sol

@@ -4,25 +4,49 @@ pragma solidity ^0.8.18;
 import { IZNSAccessController } from "./IZNSAccessController.sol";
 
 
+/**
+ * @title This abstract contract outlines basic functionality, declares functions
+ * that need to be implemented to provide a deterministic connection to `ZNSAccessController` module.
+ * @dev In order to connect an arbitrary module to `ZNSAccessController` and it's functionality,
+ * this contract needs to be inherited by the module.
+ */
 abstract contract AccessControlled {
 
+    /**
+     * @notice Emitted when the access controller contract address is set.
+     */
     event AccessControllerSet(address accessController);
 
+    /**
+     * @notice Address of the ZNSAccessController contract.
+     */
     IZNSAccessController internal accessController;
 
+    /**
+     * @notice Modifier to make a function callable only when caller is an admin.
+     * Implemented here to avoid declaring this in every single contract that uses it.
+     */
     modifier onlyAdmin() {
         accessController.checkAdmin(msg.sender);
         _;
     }
 
     /**
-     * @dev These 2 virtual functions are here to make sure they are always implemented in children,
-     * otherwise we will not be able to reset the module or read the AC address
+     * @notice Virtual function to make sure the getter is always implemented in children,
+     * otherwise we will not be able to read the AC address in children
      */
     function getAccessController() external view virtual returns (address);
 
+    /**
+     * @notice Virtual function to make sure the setter is always implemented in children,
+     * otherwise we will not be able to reset the AC address in children
+     */
     function setAccessController(address _accessController) external virtual;
 
+    /**
+     * @notice Internal function to set the access controller address.
+     * @param _accessController Address of the ZNSAccessController contract.
+     */
     function _setAccessController(address _accessController) internal {
         require(_accessController != address(0), "AC: _accessController is 0x0 address");
         accessController = IZNSAccessController(_accessController);

contracts/access/ZNSAccessController.sol

@@ -6,6 +6,18 @@ import { IZNSAccessController } from "./IZNSAccessController.sol";
 import { ZNSRoles } from "./ZNSRoles.sol";
 
 
+/**
+ * @title The main module for system-wide Access Control.
+ * @dev ZNS Business Logic Contract access to this module is outlined in `AccessControlled`.
+ * Uses a role-based access control scheme with levels:
+ * - GOVERNOR: The highest rank, assigns Admins, new roles and Role Admins
+ * - ADMIN: The main maintainer role, that gets access to all system functions (managed by Governor)
+ * - EXECUTOR: Can be here to future proof, if we need a new role (managed by Governor)
+ * - REGISTRAR: This role is here specifically for the ZNSRegistrar contract (managed by Admin)
+ *
+ * > This contract is NOT proxied. When new implementation is needed, a new contract will be deployed
+ * and all modules will be updated to use the new address, since they all inherit from `AccessControlled`.
+ */
 contract ZNSAccessController is AccessControl, ZNSRoles, IZNSAccessController {
     constructor(
         address[] memory governorAddresses,

contracts/access/ZNSRoles.sol

@@ -2,14 +2,29 @@
 pragma solidity ^0.8.18;
 
 
+/**
+ * @title Outlines the roles used in the ZNS system
+ * @dev > Inherited ONLY by `ZNSAccessController`
+ */
 abstract contract ZNSRoles {
-    // the highest rank, assigns Admins, new roles and Role Admins
+    /**
+     * @notice The highest rank, assigns Admins, new roles and Role Admins
+     */
     bytes32 public constant GOVERNOR_ROLE = keccak256("GOVERNOR_ROLE");
-    // the main maintainer role, that gets access to all system functions
+
+    /**
+     * @notice The main maintainer role, that gets access to all system functions
+     */
     bytes32 public constant ADMIN_ROLE = keccak256("ADMIN_ROLE");
-    // executor can be here to future proof, if we need a new role
-    // so we don't have to upgrade all contracts
+
+    /**
+     * @notice Executor can be here to future proof, if we need a new role
+     * so we don't have to upgrade all contracts
+     */
     bytes32 public constant EXECUTOR_ROLE = keccak256("EXECUTOR_ROLE");
-    // this role is here specifically for the ZNSRegistrar contract
+
+    /**
+     * @notice This role is here specifically for the ZNSRegistrar contract
+     */
     bytes32 public constant REGISTRAR_ROLE = keccak256("REGISTRAR_ROLE");
 }

contracts/distribution/IZNSPriceOracle.sol

@@ -2,13 +2,64 @@
 pragma solidity ^0.8.18;
 
 
+/**
+ * @dev **`DomainPriceConfig` struct properties:**
+ *
+ * - `maxPrice` (uint256): Maximum price for a domain returned at <= `baseLength`
+ * - `minPrice` (uint256): Minimum price for a domain returned at > `maxLength`
+ * - `maxLength` (uint256): Maximum length of a domain name. If the name is longer than this value we return the `minPrice`
+ * - `baseLength` (uint256): Base length of a domain name. If the name is less than or equal to this value we return the `maxPrice`
+ * - `precisionMultiplier` (uint256): The precision multiplier of the price. This multiplier
+ * should be picked based on the number of token decimals to calculate properly.
+ * e.g. if we use a token with 18 decimals, and want precision of 2,
+ * our precision multiplier will be equal 10^18 - 10^2 = 10^16
+ */
 interface IZNSPriceOracle {
+
+    /**
+     * @notice Emitted when the `maxPrice` is set in `rootDomainPriceConfig`
+     * @param price The new maxPrice value
+     */
     event MaxPriceSet(uint256 price);
+
+    /**
+     * @notice Emitted when the `minPrice` is set in `rootDomainPriceConfig`
+     * @param price The new minPrice value
+     */
     event MinPriceSet(uint256 price);
+
+    /**
+     * @notice Emitted when the `baseLength` is set in `rootDomainPriceConfig`
+     * @param length The new baseLength value
+     */
     event BaseLengthSet(uint256 length);
+
+    /**
+     * @notice Emitted when the `maxLength` is set in `rootDomainPriceConfig`
+     * @param length The new maxLength value
+     */
     event MaxLengthSet(uint256 length);
+
+    /**
+     * @notice Emitted when the `precisionMultiplier` is set in `rootDomainPriceConfig`
+     * @param precision The new precisionMultiplier value
+     */
     event PrecisionMultiplierSet(uint256 precision);
+
+    /**
+     * @notice Emitted when the `feePercentage` is set in state
+     * @param feePercentage The new feePercentage value
+     */
     event FeePercentageSet(uint256 feePercentage);
+
+    /**
+     * @notice Emitted when the full `rootDomainPriceConfig` is set in state
+     * @param maxPrice The new `maxPrice` value
+     * @param minPrice The new `minPrice` value
+     * @param maxLength The new `maxLength` value
+     * @param baseLength The new `baseLength` value
+     * @param precisionMultiplier The new `precisionMultiplier` value
+     */
     event PriceConfigSet(
         uint256 maxPrice,
         uint256 minPrice,
@@ -18,15 +69,16 @@ interface IZNSPriceOracle {
     );
 
     /**
-     * @notice Struct for each configurable price variable
+     * @notice Struct for each configurable variable for price calculations.
+     * Does NOT include variables for calcs of registration fees.
      */
     struct DomainPriceConfig {
         /**
-         * @notice Maximum price for a domain
+         * @notice Maximum price for a domain returned at <= `baseLength`
         */
         uint256 maxPrice;
         /**
-         * @notice Minimum price for a domain
+         * @notice Minimum price for a domain returned at > `maxLength`
          */
         uint256 minPrice;
         /**
@@ -54,10 +106,6 @@ interface IZNSPriceOracle {
         uint256 regFeePercentage_
     ) external;
 
-    /**
-     * @notice Get the price of a given domain name length
-     * @param name The name of the domain to check
-     */
     function getPrice(
         string calldata name
     ) external view returns (
@@ -66,28 +114,14 @@ interface IZNSPriceOracle {
         uint256 fee
     );
 
-    /**
-     * @notice Returns the registration fee based on domain price
-     * @param domainPrice Price of the domain in question
-     */
     function getRegistrationFee(uint256 domainPrice) external view returns (uint256);
 
     function setPriceConfig(DomainPriceConfig calldata priceConfig) external;
 
-    /**
-     * @notice Set the base price for root domains
-     *
-     * @param maxPrice The price to set in $ZERO
-     */
     function setMaxPrice(uint256 maxPrice) external;
 
     function setMinPrice(uint256 minPrice) external;
 
-    /**
-     * @notice Set the value of the domain name length boundary where the default price applies
-     * e.g. A value of '5' means all domains <= 5 in length cost the default price
-     * @param length Boundary to set
-     */
     function setBaseLength(uint256 length) external;
 
     function setMaxLength(uint256 length) external;

contracts/distribution/IZNSRegistrar.sol

@@ -3,6 +3,20 @@ pragma solidity ^0.8.18;
 
 
 interface IZNSRegistrar {
+
+    /**
+     * @notice Emitted when a NEW domain is registered.
+     * @dev `domainAddress` parameter is the address to which a domain name will relate to in ZNS.
+     * E.g. if a user made a domain for his wallet, the address of the wallet will be the `domainAddress`.
+     * This can be 0 as this variable is not required to perform registration process
+     * and can be set at a later time by the domain owner.
+     * @param domainHash The hash of the domain registered
+     * @param tokenId The tokenId of the domain registered
+     * @param name The name as string of the domain registered
+     * @param registrant The address that called `ZNSRegistrar.registerDomain()`
+     * @param resolver The resolver contract address of the domain registered
+     * @param domainAddress The domain address of the domain registered
+     */
     event DomainRegistered(
         bytes32 indexed domainHash,
         uint256 indexed tokenId,
@@ -12,19 +26,45 @@ interface IZNSRegistrar {
         address domainAddress
     );
 
+    /**
+     * @notice Emitted when a domain is revoked.
+     * @param domainHash The hash of the domain revoked
+     * @param registrant The address that called `ZNSRegistrar.revokeDomain()`
+     */
     event DomainRevoked(bytes32 indexed domainHash, address indexed registrant);
 
+    /**
+     * @notice Emitted when an ownership of the Name is reclaimed by the Token owner.
+     * @param domainHash The hash of the domain reclaimed
+     * @param registrant The address that called `ZNSRegistrar.reclaimDomain()`
+     */
     event DomainReclaimed(
         bytes32 indexed domainHash,
         address indexed registrant
     );
 
+    /**
+     * @notice Emitted when the `registry` address is set in state.
+     * @param registry The new address of the registry contract
+     */
     event RegistrySet(address registry);
 
+    /**
+     * @notice Emitted when the `treasury` address is set in state.
+     * @param treasury The new address of the treasury contract
+     */
     event TreasurySet(address treasury);
 
+    /**
+     * @notice Emitted when the `domainToken` address is set in state.
+     * @param domainToken The new address of the domainToken contract
+     */
     event DomainTokenSet(address domainToken);
 
+    /**
+     * @notice Emitted when the `addressResolver` address is set in state.
+     * @param addressResolver The new address of the addressResolver contract
+     */
     event AddressResolverSet(address addressResolver);
 
     function registerDomain(

contracts/distribution/IZNSTreasury.sol

@@ -4,11 +4,12 @@ pragma solidity ^0.8.18;
 
 interface IZNSTreasury {
     /**
-     * @notice Emitted when a new stake is deposited
+     * @notice Emitted when a new stake is deposited upon registration of a new domain.
      * @param domainHash The hash of the domain name
-     * @param domainName The domain name
-     * @param depositor The address of the depositing user
-     * @param stakeAmount The amount they are depositing
+     * @param domainName The domain name as a string
+     * @param depositor The address of the depositing user / new domain owner
+     * @param stakeAmount The amount they are depositing / price of the domain based on name length
+     * @param registrationFee The registration fee paid by the user on top of the staked amount
      */
     event StakeDeposited(
         bytes32 indexed domainHash,
@@ -19,21 +20,33 @@ interface IZNSTreasury {
     );
 
     /**
-     * @notice Emitted when a stake is withdrawn
-     * @param domainHash The hash of the domain name
-     * @param owner The owner of the domain
-     * @param stakeAmount The staked amount withdrawn
+     * @notice Emitted when a stake is withdrawn upon domain revocation.
+     * @param domainHash The hash of the domain name being revoked
+     * @param owner The owner of the domain being revoked
+     * @param stakeAmount The staked amount withdrawn to the user after revoking
      */
     event StakeWithdrawn(
         bytes32 indexed domainHash,
         address indexed owner,
         uint256 indexed stakeAmount
     );
 
+    /**
+     * @notice Emitted when `priceOracle` is set in state.
+     * @param priceOracle The new address of the price oracle contract
+     */
     event PriceOracleSet(address priceOracle);
 
+    /**
+     * @notice Emitted when `stakingToken` is set in state.
+     * @param stakingToken The new address of the ERC-20 compliant staking token contract
+     */
     event StakingTokenSet(address stakingToken);
 
+    /**
+     * @notice Emitted when `zeroVault` is set in state.
+     * @param zeroVault The new address of the zero vault contract or wallet
+     */
     event ZeroVaultAddressSet(address zeroVault);
 
     function stakeForDomain(