Merge pull request #6381 from ethereum-optimism/refcell/op-nft-styling

fix(ctb): Port op-nft periphery contracts to triple slash natspec styling

packages/contracts-bedrock/contracts/periphery/op-nft/AttestationStation.sol

@@ -3,39 +3,29 @@ pragma solidity 0.8.15;
 
 import { Semver } from "../../universal/Semver.sol";
 
-/**
- * @title AttestationStation
- * @author Optimism Collective
- * @author Gitcoin
- * @notice Where attestations live.
- */
+/// @title AttestationStation
+/// @author Optimism Collective
+/// @author Gitcoin
+/// @notice Where attestations live.
 contract AttestationStation is Semver {
-    /**
-     * @notice Struct representing data that is being attested.
-     *
-     * @custom:field about Address for which the attestation is about.
-     * @custom:field key   A bytes32 key for the attestation.
-     * @custom:field val   The attestation as arbitrary bytes.
-     */
+    /// @notice Struct representing data that is being attested.
+    /// @custom:field about Address for which the attestation is about.
+    /// @custom:field key   A bytes32 key for the attestation.
+    /// @custom:field val   The attestation as arbitrary bytes.
     struct AttestationData {
         address about;
         bytes32 key;
         bytes val;
     }
 
-    /**
-     * @notice Maps addresses to attestations. Creator => About => Key => Value.
-     */
+    /// @notice Maps addresses to attestations. Creator => About => Key => Value.
     mapping(address => mapping(address => mapping(bytes32 => bytes))) public attestations;
 
-    /**
-     * @notice Emitted when Attestation is created.
-     *
-     * @param creator Address that made the attestation.
-     * @param about   Address attestation is about.
-     * @param key     Key of the attestation.
-     * @param val     Value of the attestation.
-     */
+    /// @notice Emitted when Attestation is created.
+    /// @param creator Address that made the attestation.
+    /// @param about   Address attestation is about.
+    /// @param key     Key of the attestation.
+    /// @param val     Value of the attestation.
     event AttestationCreated(
         address indexed creator,
         address indexed about,
@@ -43,18 +33,13 @@ contract AttestationStation is Semver {
         bytes val
     );
 
-    /**
-     * @custom:semver 1.1.0
-     */
+    /// @custom:semver 1.1.0
     constructor() Semver(1, 1, 0) {}
 
-    /**
-     * @notice Allows anyone to create an attestation.
-     *
-     * @param _about Address that the attestation is about.
-     * @param _key   A key used to namespace the attestation.
-     * @param _val   An arbitrary value stored as part of the attestation.
-     */
+    /// @notice Allows anyone to create an attestation.
+    /// @param _about Address that the attestation is about.
+    /// @param _key   A key used to namespace the attestation.
+    /// @param _val   An arbitrary value stored as part of the attestation.
     function attest(
         address _about,
         bytes32 _key,
@@ -65,11 +50,8 @@ contract AttestationStation is Semver {
         emit AttestationCreated(msg.sender, _about, _key, _val);
     }
 
-    /**
-     * @notice Allows anyone to create attestations.
-     *
-     * @param _attestations An array of AttestationData structs.
-     */
+    /// @notice Allows anyone to create attestations.
+    /// @param _attestations An array of AttestationData structs.
     function attest(AttestationData[] calldata _attestations) external {
         uint256 length = _attestations.length;
         for (uint256 i = 0; i < length; ) {

packages/contracts-bedrock/contracts/periphery/op-nft/Optimist.sol

@@ -9,41 +9,29 @@ import { AttestationStation } from "./AttestationStation.sol";
 import { OptimistAllowlist } from "./OptimistAllowlist.sol";
 import { Strings } from "@openzeppelin/contracts/utils/Strings.sol";
 
-/**
- * @author Optimism Collective
- * @author Gitcoin
- * @title  Optimist
- * @notice A Soul Bound Token for real humans only(tm).
- */
+/// @author Optimism Collective
+/// @author Gitcoin
+/// @title  Optimist
+/// @notice A Soul Bound Token for real humans only(tm).
 contract Optimist is ERC721BurnableUpgradeable, Semver {
-    /**
-     * @notice Attestation key used by the attestor to attest the baseURI.
-     */
+    /// @notice Attestation key used by the attestor to attest the baseURI.
     bytes32 public constant BASE_URI_ATTESTATION_KEY = bytes32("optimist.base-uri");
 
-    /**
-     * @notice Attestor who attests to baseURI.
-     */
+    /// @notice Attestor who attests to baseURI.
     address public immutable BASE_URI_ATTESTOR;
 
-    /**
-     * @notice Address of the AttestationStation contract.
-     */
+    /// @notice Address of the AttestationStation contract.
     AttestationStation public immutable ATTESTATION_STATION;
 
-    /**
-     * @notice Address of the OptimistAllowlist contract.
-     */
+    /// @notice Address of the OptimistAllowlist contract.
     OptimistAllowlist public immutable OPTIMIST_ALLOWLIST;
 
-    /**
-     * @custom:semver 2.0.0
-     * @param _name               Token name.
-     * @param _symbol             Token symbol.
-     * @param _baseURIAttestor    Address of the baseURI attestor.
-     * @param _attestationStation Address of the AttestationStation contract.
-     * @param _optimistAllowlist  Address of the OptimistAllowlist contract
-     */
+    /// @custom:semver 2.0.0
+    /// @param _name               Token name.
+    /// @param _symbol             Token symbol.
+    /// @param _baseURIAttestor    Address of the baseURI attestor.
+    /// @param _attestationStation Address of the AttestationStation contract.
+    /// @param _optimistAllowlist  Address of the OptimistAllowlist contract
     constructor(
         string memory _name,
         string memory _symbol,
@@ -57,109 +45,81 @@ contract Optimist is ERC721BurnableUpgradeable, Semver {
         initialize(_name, _symbol);
     }
 
-    /**
-     * @notice Initializes the Optimist contract.
-     *
-     * @param _name   Token name.
-     * @param _symbol Token symbol.
-     */
+    /// @notice Initializes the Optimist contract.
+    /// @param _name   Token name.
+    /// @param _symbol Token symbol.
     function initialize(string memory _name, string memory _symbol) public initializer {
         __ERC721_init(_name, _symbol);
         __ERC721Burnable_init();
     }
 
-    /**
-     * @notice Allows an address to mint an Optimist NFT. Token ID is the uint256 representation
-     *         of the recipient's address. Recipients must be permitted to mint, eventually anyone
-     *         will be able to mint. One token per address.
-     *
-     * @param _recipient Address of the token recipient.
-     */
+    /// @notice Allows an address to mint an Optimist NFT. Token ID is the uint256 representation
+    ///         of the recipient's address. Recipients must be permitted to mint, eventually anyone
+    ///         will be able to mint. One token per address.
+    /// @param _recipient Address of the token recipient.
     function mint(address _recipient) public {
         require(isOnAllowList(_recipient), "Optimist: address is not on allowList");
         _safeMint(_recipient, tokenIdOfAddress(_recipient));
     }
 
-    /**
-     * @notice Returns the baseURI for all tokens.
-     *
-     * @return BaseURI for all tokens.
-     */
-    function baseURI() public view returns (string memory) {
-        return
-            string(
-                abi.encodePacked(
-                    ATTESTATION_STATION.attestations(
-                        BASE_URI_ATTESTOR,
-                        address(this),
-                        bytes32("optimist.base-uri")
-                    )
+    /// @notice Returns the baseURI for all tokens.
+    /// @return uri_ BaseURI for all tokens.
+    function baseURI() public view returns (string memory uri_) {
+        uri_ = string(
+            abi.encodePacked(
+                ATTESTATION_STATION.attestations(
+                    BASE_URI_ATTESTOR,
+                    address(this),
+                    bytes32("optimist.base-uri")
                 )
-            );
+            )
+        );
     }
 
-    /**
-     * @notice Returns the token URI for a given token by ID
-     *
-     * @param _tokenId Token ID to query.
-
-     * @return Token URI for the given token by ID.
-     */
-    function tokenURI(uint256 _tokenId) public view virtual override returns (string memory) {
-        return
-            string(
-                abi.encodePacked(
-                    baseURI(),
-                    "/",
-                    // Properly format the token ID as a 20 byte hex string (address).
-                    Strings.toHexString(_tokenId, 20),
-                    ".json"
-                )
-            );
+    /// @notice Returns the token URI for a given token by ID
+    /// @param _tokenId Token ID to query.
+    /// @return uri_ Token URI for the given token by ID.
+    function tokenURI(uint256 _tokenId) public view virtual override returns (string memory uri_) {
+        uri_ = string(
+            abi.encodePacked(
+                baseURI(),
+                "/",
+                // Properly format the token ID as a 20 byte hex string (address).
+                Strings.toHexString(_tokenId, 20),
+                ".json"
+            )
+        );
     }
 
-    /**
-     * @notice Checks OptimistAllowlist to determine whether a given address is allowed to mint
-     *         the Optimist NFT. Since the Optimist NFT will also be used as part of the
-     *         Citizens House, mints are currently restricted. Eventually anyone will be able
-     *         to mint.
-     *
-     * @return Whether or not the address is allowed to mint yet.
-     */
-    function isOnAllowList(address _recipient) public view returns (bool) {
-        return OPTIMIST_ALLOWLIST.isAllowedToMint(_recipient);
+    /// @notice Checks OptimistAllowlist to determine whether a given address is allowed to mint
+    ///         the Optimist NFT. Since the Optimist NFT will also be used as part of the
+    ///         Citizens House, mints are currently restricted. Eventually anyone will be able
+    ///         to mint.
+    /// @return allowed_ Whether or not the address is allowed to mint yet.
+    function isOnAllowList(address _recipient) public view returns (bool allowed_) {
+        allowed_ = OPTIMIST_ALLOWLIST.isAllowedToMint(_recipient);
     }
 
-    /**
-     * @notice Returns the token ID for the token owned by a given address. This is the uint256
-     *         representation of the given address.
-     *
-     * @return Token ID for the token owned by the given address.
-     */
+    /// @notice Returns the token ID for the token owned by a given address. This is the uint256
+    ///         representation of the given address.
+    /// @return Token ID for the token owned by the given address.
     function tokenIdOfAddress(address _owner) public pure returns (uint256) {
         return uint256(uint160(_owner));
     }
 
-    /**
-     * @notice Disabled for the Optimist NFT (Soul Bound Token).
-     */
+    /// @notice Disabled for the Optimist NFT (Soul Bound Token).
     function approve(address, uint256) public pure override {
         revert("Optimist: soul bound token");
     }
 
-    /**
-     * @notice Disabled for the Optimist NFT (Soul Bound Token).
-     */
+    /// @notice Disabled for the Optimist NFT (Soul Bound Token).
     function setApprovalForAll(address, bool) public virtual override {
         revert("Optimist: soul bound token");
     }
 
-    /**
-     * @notice Prevents transfers of the Optimist NFT (Soul Bound Token).
-     *
-     * @param _from Address of the token sender.
-     * @param _to   Address of the token recipient.
-     */
+    /// @notice Prevents transfers of the Optimist NFT (Soul Bound Token).
+    /// @param _from Address of the token sender.
+    /// @param _to   Address of the token recipient.
     function _beforeTokenTransfer(
         address _from,
         address _to,

packages/contracts-bedrock/contracts/periphery/op-nft/OptimistAllowlist.sol

@@ -5,54 +5,37 @@ import { Semver } from "../../universal/Semver.sol";
 import { AttestationStation } from "./AttestationStation.sol";
 import { OptimistConstants } from "./libraries/OptimistConstants.sol";
 
-/**
- * @title  OptimistAllowlist
- * @notice Source of truth for whether an address is able to mint an Optimist NFT.
-           isAllowedToMint function checks various signals to return boolean value for whether an
-           address is eligible or not.
- */
+/// @title  OptimistAllowlist
+/// @notice Source of truth for whether an address is able to mint an Optimist NFT.
+///         isAllowedToMint function checks various signals to return boolean value
+///         for whether an address is eligible or not.
 contract OptimistAllowlist is Semver {
-    /**
-     * @notice Attestation key used by the AllowlistAttestor to manually add addresses to the
-     *         allowlist.
-     */
+    /// @notice Attestation key used by the AllowlistAttestor to manually add addresses to the
+    ///         allowlist.
     bytes32 public constant OPTIMIST_CAN_MINT_ATTESTATION_KEY = bytes32("optimist.can-mint");
 
-    /**
-     * @notice Attestation key used by Coinbase to issue attestations for Quest participants.
-     */
+    /// @notice Attestation key used by Coinbase to issue attestations for Quest participants.
     bytes32 public constant COINBASE_QUEST_ELIGIBLE_ATTESTATION_KEY =
         bytes32("coinbase.quest-eligible");
 
-    /**
-     * @notice Address of the AttestationStation contract.
-     */
+    /// @notice Address of the AttestationStation contract.
     AttestationStation public immutable ATTESTATION_STATION;
 
-    /**
-     * @notice Attestor that issues 'optimist.can-mint' attestations.
-     */
+    /// @notice Attestor that issues 'optimist.can-mint' attestations.
     address public immutable ALLOWLIST_ATTESTOR;
 
-    /**
-     * @notice Attestor that issues 'coinbase.quest-eligible' attestations.
-     */
+    /// @notice Attestor that issues 'coinbase.quest-eligible' attestations.
     address public immutable COINBASE_QUEST_ATTESTOR;
 
-    /**
-     * @notice Address of OptimistInviter contract that issues 'optimist.can-mint-from-invite'
-     *         attestations.
-     */
+    /// @notice Address of OptimistInviter contract that issues 'optimist.can-mint-from-invite'
+    ///         attestations.
     address public immutable OPTIMIST_INVITER;
 
-    /**
-     * @custom:semver 1.0.0
-     *
-     * @param _attestationStation    Address of the AttestationStation contract.
-     * @param _allowlistAttestor     Address of the allowlist attestor.
-     * @param _coinbaseQuestAttestor Address of the Coinbase Quest attestor.
-     * @param _optimistInviter       Address of the OptimistInviter contract.
-     */
+    /// @custom:semver 1.0.0
+    /// @param _attestationStation    Address of the AttestationStation contract.
+    /// @param _allowlistAttestor     Address of the allowlist attestor.
+    /// @param _coinbaseQuestAttestor Address of the Coinbase Quest attestor.
+    /// @param _optimistInviter       Address of the OptimistInviter contract.
     constructor(
         AttestationStation _attestationStation,
         address _allowlistAttestor,
@@ -65,95 +48,83 @@ contract OptimistAllowlist is Semver {
         OPTIMIST_INVITER = _optimistInviter;
     }
 
-    /**
-     * @notice Checks whether a given address is allowed to mint the Optimist NFT yet. Since the
-     *         Optimist NFT will also be used as part of the Citizens House, mints are currently
-     *         restricted. Eventually anyone will be able to mint.
-     *
-     *         Currently, address is allowed to mint if it satisfies any of the following:
-     *         1) Has a valid 'optimist.can-mint' attestation from the allowlist attestor.
-     *         2) Has a valid 'coinbase.quest-eligible' attestation from Coinbase Quest attestor
-     *         3) Has a valid 'optimist.can-mint-from-invite' attestation from the OptimistInviter
-     *            contract.
-     *
-     * @param _claimer Address to check.
-     *
-     * @return Whether or not the address is allowed to mint yet.
-     */
-    function isAllowedToMint(address _claimer) public view returns (bool) {
-        return
+    /// @notice Checks whether a given address is allowed to mint the Optimist NFT yet. Since the
+    ///         Optimist NFT will also be used as part of the Citizens House, mints are currently
+    ///         restricted. Eventually anyone will be able to mint.
+    ///         Currently, address is allowed to mint if it satisfies any of the following:
+    ///          1) Has a valid 'optimist.can-mint' attestation from the allowlist attestor.
+    ///          2) Has a valid 'coinbase.quest-eligible' attestation from Coinbase Quest attestor
+    ///          3) Has a valid 'optimist.can-mint-from-invite' attestation from the OptimistInviter
+    ///             contract.
+    /// @param _claimer Address to check.
+    /// @return allowed_ Whether or not the address is allowed to mint yet.
+    function isAllowedToMint(address _claimer) public view returns (bool allowed_) {
+        allowed_ =
             _hasAttestationFromAllowlistAttestor(_claimer) ||
             _hasAttestationFromCoinbaseQuestAttestor(_claimer) ||
             _hasAttestationFromOptimistInviter(_claimer);
     }
 
-    /**
-     * @notice Checks whether an address has a valid 'optimist.can-mint' attestation from the
-     *         allowlist attestor.
-     *
-     * @param _claimer Address to check.
-     *
-     * @return Whether or not the address has a valid attestation.
-     */
-    function _hasAttestationFromAllowlistAttestor(address _claimer) internal view returns (bool) {
+    /// @notice Checks whether an address has a valid 'optimist.can-mint' attestation from the
+    ///         allowlist attestor.
+    /// @param _claimer Address to check.
+    /// @return valid_ Whether or not the address has a valid attestation.
+    function _hasAttestationFromAllowlistAttestor(address _claimer)
+        internal
+        view
+        returns (bool valid_)
+    {
         // Expected attestation value is bytes32("true")
-        return
-            _hasValidAttestation(ALLOWLIST_ATTESTOR, _claimer, OPTIMIST_CAN_MINT_ATTESTATION_KEY);
+        valid_ = _hasValidAttestation(
+            ALLOWLIST_ATTESTOR,
+            _claimer,
+            OPTIMIST_CAN_MINT_ATTESTATION_KEY
+        );
     }
 
-    /**
-     * @notice Checks whether an address has a valid attestation from the Coinbase attestor.
-     *
-     * @param _claimer Address to check.
-     *
-     * @return Whether or not the address has a valid attestation.
-     */
+    /// @notice Checks whether an address has a valid attestation from the Coinbase attestor.
+    /// @param _claimer Address to check.
+    /// @return valid_ Whether or not the address has a valid attestation.
     function _hasAttestationFromCoinbaseQuestAttestor(address _claimer)
         internal
         view
-        returns (bool)
+        returns (bool valid_)
     {
         // Expected attestation value is bytes32("true")
-        return
-            _hasValidAttestation(
-                COINBASE_QUEST_ATTESTOR,
-                _claimer,
-                COINBASE_QUEST_ELIGIBLE_ATTESTATION_KEY
-            );
+        valid_ = _hasValidAttestation(
+            COINBASE_QUEST_ATTESTOR,
+            _claimer,
+            COINBASE_QUEST_ELIGIBLE_ATTESTATION_KEY
+        );
     }
 
-    /**
-     * @notice Checks whether an address has a valid attestation from the OptimistInviter contract.
-     *
-     * @param _claimer Address to check.
-     *
-     * @return Whether or not the address has a valid attestation.
-     */
-    function _hasAttestationFromOptimistInviter(address _claimer) internal view returns (bool) {
+    /// @notice Checks whether an address has a valid attestation from the OptimistInviter contract.
+    /// @param _claimer Address to check.
+    /// @return valid_ Whether or not the address has a valid attestation.
+    function _hasAttestationFromOptimistInviter(address _claimer)
+        internal
+        view
+        returns (bool valid_)
+    {
         // Expected attestation value is the inviter's address
-        return
-            _hasValidAttestation(
-                OPTIMIST_INVITER,
-                _claimer,
-                OptimistConstants.OPTIMIST_CAN_MINT_FROM_INVITE_ATTESTATION_KEY
-            );
+        valid_ = _hasValidAttestation(
+            OPTIMIST_INVITER,
+            _claimer,
+            OptimistConstants.OPTIMIST_CAN_MINT_FROM_INVITE_ATTESTATION_KEY
+        );
     }
 
-    /**
-     * @notice Checks whether an address has a valid truthy attestation.
-     *         Any attestation val other than bytes32("") is considered truthy.
-     *
-     * @param _creator Address that made the attestation.
-     * @param _about   Address attestation is about.
-     * @param _key     Key of the attestation.
-     *
-     * @return Whether or not the address has a valid truthy attestation.
-     */
+    /// @notice Checks whether an address has a valid truthy attestation.
+    ///         Any attestation val other than bytes32("") is considered truthy.
+    /// @param _creator Address that made the attestation.
+    /// @param _about   Address attestation is about.
+    /// @param _key     Key of the attestation.
+    /// @return valid_ Whether or not the address has a valid truthy attestation.
     function _hasValidAttestation(
         address _creator,
         address _about,
         bytes32 _key
-    ) internal view returns (bool) {
-        return ATTESTATION_STATION.attestations(_creator, _about, _key).length > 0;
+    ) internal view returns (bool valid_) {
+        valid_ = ATTESTATION_STATION.attestations(_creator, _about, _key).length > 0;
     }
 }

packages/contracts-bedrock/contracts/periphery/op-nft/libraries/OptimistConstants.sol

 // SPDX-License-Identifier: MIT
 pragma solidity 0.8.15;
 
-/**
- * @title  OptimistConstants
- * @notice Library for storing Optimist related constants that are shared in multiple contracts.
- */
-
+/// @title  OptimistConstants
+/// @notice Library for storing Optimist related constants that are shared in multiple contracts.
 library OptimistConstants {
-    /**
-     * @notice Attestation key issued by OptimistInviter allowing the attested account to mint.
-     */
+    /// @notice Attestation key issued by OptimistInviter allowing the attested account to mint.
     bytes32 internal constant OPTIMIST_CAN_MINT_FROM_INVITE_ATTESTATION_KEY =
         bytes32("optimist.can-mint-from-invite");
 }