Add custom errors to docs (#4480)

OpenZeppelin · Jul 27, 2023 · 02ea017 · 02ea017
1 parent 9445f96
commit 02ea017
Show file tree

Hide file tree

Showing 5 changed files with 47 additions and 11 deletions.
diff --git a/contracts/access/AccessControl.sol b/contracts/access/AccessControl.sol
@@ -58,8 +58,7 @@ abstract contract AccessControl is Context, IAccessControl, ERC165 {
 
     /**
      * @dev Modifier that checks that an account has a specific role. Reverts
-     * with a custom error including the required role.
-     *
+     * with an {AccessControlUnauthorizedAccount} error including the required role.
      */
     modifier onlyRole(bytes32 role) {
         _checkRole(role);
@@ -81,15 +80,16 @@ abstract contract AccessControl is Context, IAccessControl, ERC165 {
     }
 
     /**
-     * @dev Revert with a custom error if `_msgSender()` is missing `role`.
-     * Overriding this function changes the behavior of the {onlyRole} modifier.
+     * @dev Reverts with an {AccessControlUnauthorizedAccount} error if `_msgSender()`
+     * is missing `role`. Overriding this function changes the behavior of the {onlyRole} modifier.
      */
     function _checkRole(bytes32 role) internal view virtual {
         _checkRole(role, _msgSender());
     }
 
     /**
-     * @dev Revert with a custom error if `account` is missing `role`.
+     * @dev Reverts with an {AccessControlUnauthorizedAccount} error if `account`
+     * is missing `role`.
      */
     function _checkRole(bytes32 role, address account) internal view virtual {
         if (!hasRole(role, account)) {

diff --git a/contracts/interfaces/README.adoc b/contracts/interfaces/README.adoc
@@ -8,18 +8,21 @@ These interfaces are available as `.sol` files, and also as compiler `.json` ABI
 are useful to interact with third party contracts that implement them.
 
 - {IERC20}
+- {IERC20Errors}
 - {IERC20Metadata}
 - {IERC165}
 - {IERC721}
 - {IERC721Receiver}
 - {IERC721Enumerable}
 - {IERC721Metadata}
+- {IERC721Errors}
 - {IERC777}
 - {IERC777Recipient}
 - {IERC777Sender}
 - {IERC1155}
 - {IERC1155Receiver}
 - {IERC1155MetadataURI}
+- {IERC1155Errors}
 - {IERC1271}
 - {IERC1363}
 - {IERC1363Receiver}
@@ -40,6 +43,12 @@ are useful to interact with third party contracts that implement them.
 
 == Detailed ABI
 
+{{IERC20Errors}}
+
+{{IERC721Errors}}
+
+{{IERC1155Errors}}
+
 {{IERC1271}}
 
 {{IERC1363}}

diff --git a/contracts/interfaces/draft-IERC6093.sol b/contracts/interfaces/draft-IERC6093.sol
@@ -3,8 +3,7 @@ pragma solidity ^0.8.19;
 
 /**
  * @dev Standard ERC20 Errors
- * Interface of the ERC6093 custom errors for ERC20 tokens
- * as defined in https://eips.ethereum.org/EIPS/eip-6093
+ * Interface of the https://eips.ethereum.org/EIPS/eip-6093[ERC-6093] custom errors for ERC20 tokens.
  */
 interface IERC20Errors {
     /**
@@ -50,8 +49,7 @@ interface IERC20Errors {
 
 /**
  * @dev Standard ERC721 Errors
- * Interface of the ERC6093 custom errors for ERC721 tokens
- * as defined in https://eips.ethereum.org/EIPS/eip-6093
+ * Interface of the https://eips.ethereum.org/EIPS/eip-6093[ERC-6093] custom errors for ERC721 tokens.
  */
 interface IERC721Errors {
     /**
@@ -109,8 +107,7 @@ interface IERC721Errors {
 
 /**
  * @dev Standard ERC1155 Errors
- * Interface of the ERC6093 custom errors for ERC1155 tokens
- * as defined in https://eips.ethereum.org/EIPS/eip-6093
+ * Interface of the https://eips.ethereum.org/EIPS/eip-6093[ERC-6093] custom errors for ERC1155 tokens.
  */
 interface IERC1155Errors {
     /**

diff --git a/docs/templates/contract.hbs b/docs/templates/contract.hbs
@@ -57,6 +57,23 @@ import "@openzeppelin/{{__item_context.file.absolutePath}}";
 --
 {{/if}}
 
+{{#if has-errors}}
+[.contract-index]
+.Errors
+--
+{{#each inheritance}}
+{{#unless @first}}
+[.contract-subindex-inherited]
+.{{name}}
+{{/unless}}
+{{#each errors}}
+* {xref-{{anchor~}} }[`++{{name}}({{names params}})++`]
+{{/each}}
+
+{{/each}}
+--
+{{/if}}
+
 {{#each modifiers}}
 [.contract-item]
 [[{{anchor}}]]
@@ -83,3 +100,12 @@ import "@openzeppelin/{{__item_context.file.absolutePath}}";
 {{{natspec.dev}}}
 
 {{/each}}
+
+{{#each errors}}
+[.contract-item]
+[[{{anchor}}]]
+==== `[.contract-item-name]#++{{name}}++#++({{typed-params params}})++` [.item-kind]#error#
+
+{{{natspec.dev}}}
+
+{{/each}}
diff --git a/docs/templates/properties.js b/docs/templates/properties.js
@@ -35,6 +35,10 @@ module.exports['has-events'] = function ({ item }) {
   return item.inheritance.some(c => c.events.length > 0);
 };
 
+module.exports['has-errors'] = function ({ item }) {
+  return item.inheritance.some(c => c.errors.length > 0);
+};
+
 module.exports['inherited-functions'] = function ({ item }) {
   const { inheritance } = item;
   const baseFunctions = new Set(inheritance.flatMap(c => c.functions.flatMap(f => f.baseFunctions ?? [])));