Merge branch 'release/core-contracts/12' into martinvol/AddOraclesToF…

…eeHandlersSellers

packages/protocol/contracts/common/GoldToken.sol

@@ -13,6 +13,15 @@ import "./interfaces/ICeloTokenInitializer.sol";
 import "./interfaces/ICeloVersionedContract.sol";
 import "../../contracts-0.8/common/IsL2Check.sol";
 
+/**
+ * @title ERC20 interface for the CELO token.
+ * @notice The native token was initially called "Celo Gold", but soon after
+ * mainnet launch, the community voted to change the name to "CELO". For legacy
+ * reasons, the contract itself is still called GoldToken.
+ * @dev Note that this is not a wrapper token like WETH. Thanks to the
+ * `transfer` precompile, this contract provides an ERC20 interface *directly*
+ * to the native token.
+ */
 contract GoldToken is
   Initializable,
   CalledByVm,
@@ -31,7 +40,7 @@ contract GoldToken is
   string constant NAME = "Celo native asset";
   string constant SYMBOL = "CELO";
   uint8 constant DECIMALS = 18;
-  uint256 constant CELO_SUPPLY_CAP = 1000000000 ether; // 1 billion Celo
+  uint256 constant CELO_SUPPLY_CAP = 1000000000 ether; // 1 billion CELO
   uint256 internal totalSupply_;
   // solhint-enable state-visibility
 
@@ -250,7 +259,7 @@ contract GoldToken is
 
   /**
    * @notice Gets the amount of CELO that has been burned.
-   * @return The total amount of Celo that has been sent to the burn address.
+   * @return The total amount of CELO that has been sent to the burn address.
    */
   function getBurnedAmount() public view returns (uint256) {
     return balanceOf(BURN_ADDRESS);

packages/protocol/contracts/common/Initializable.sol

@@ -1,15 +1,30 @@
 // SPDX-License-Identifier: LGPL-3.0-only
 pragma solidity >=0.5.13 <0.9.0;
 
+/**
+ * @title Used with proxied contracts that have an `initialize` function.
+ * @notice Ensures the `initialize` function:
+ *         - gets called only once
+ *         - cannot be called on the logic contract.
+ */
 contract Initializable {
   bool public initialized;
 
+  /**
+   * @notice Ensures the initializer function cannot be called more than once.
+   */
   modifier initializer() {
     require(!initialized, "contract already initialized");
     initialized = true;
     _;
   }
 
+  /**
+   * @notice By default, ensures that the `initialize` function cannot be called
+   * on the logic contract.
+   * @param testingDeployment When set to true, allows the `initialize` function
+   * to be called, which is useful in testing when not setting up with a Proxy.
+   */
   constructor(bool testingDeployment) public {
     if (!testingDeployment) {
       initialized = true;