Completed docs

Author: ernestognw

contracts/access/AccessControl.sol

@@ -44,7 +44,7 @@ import "../utils/introspection/ERC165.sol";
  *
  * WARNING: The `DEFAULT_ADMIN_ROLE` is also its own admin: it has permission to
  * grant and revoke this role. Extra precautions should be taken to secure
- * accounts that have been granted it.
+ * accounts that have been granted it. See {AccessControlAdminRules}
  */
 abstract contract AccessControl is Context, IAccessControl, ERC165 {
     struct RoleData {

contracts/access/AccessControlAdminRules.sol

@@ -9,7 +9,7 @@ import "../utils/math/SafeCast.sol";
 
 /**
  * @dev Extension of {AccessControl} that allows to specify special rules to manage
- * the `DEFAULT_ADMIN_ROLE`´s owner, which is a sensitive role with special permissions
+ * the `DEFAULT_ADMIN_ROLE` 's owner, which is a sensitive role with special permissions
  * over other valid roles that may potentially have rights.
  *
  * If a specific role doesn't have an `adminRole` assigned, the holder of the
@@ -18,12 +18,26 @@ import "../utils/math/SafeCast.sol";
  *
  * This contract implements the following risk mitigations on top of the AccessControl implementation:
  *
- * - Only one account holds the `DEFAULT_ADMIN_ROLE` at every time after construction except when renounced.
- * - Enforce a 2-step process to transfer the `DEFAULT_ADMIN_ROLE` to another account. Even when it's been renounced.
- * - Enforce a configurable delay between the two steps, with the ability to cancel in between. Even after the timer has passed to avoid locking it forever.
- * - The `DEFAULT_ADMIN_ROLE`'s admin can be only held by itself.
+ * * Only one account holds the `DEFAULT_ADMIN_ROLE` at every time after construction except when renounced.
+ * * Enforce a 2-step process to transfer the `DEFAULT_ADMIN_ROLE` to another account.
+ *   - Even when it's been renounced.
+ * * Enforce a configurable delay between the two steps, with the ability to cancel in between.
+ *   - Even after the timer has passed to avoid locking it forever.
+ * * The `DEFAULT_ADMIN_ROLE` 's admin can be only held by itself.
  *
- * NOTE: `delay` is only configurable in the constructor to avoid issues related with handling delay management during the transfer is pending to be completed.
+ * Once you understand what the {constructor} parameters, you can use this reference implementation:
+ *
+ * ```solidity
+ * contract MyToken is AccessControlAdminRules {
+ *   constructor() AccessControlAdminRules(
+ *     60 * 60 * 24, // 3 days
+ *     _msgSender() // Explicit initial `DEFAULT_ADMIN_ROLE` holder
+ *    ) {}
+ *}
+ * ```
+ *
+ * NOTE: The `delay` is only configurable in the constructor to avoid issues related with handling
+ * delay management during the transfer is pending to be completed.
  *
  * _Available since v4.9._
  */
@@ -36,13 +50,12 @@ abstract contract AccessControlAdminRules is IAccessControlAdminRules, AccessCon
     address private _pendingAdmin;
 
     /**
-     * @dev Sets the values for {name} and {symbol}.
-     *
-     * All two of these values are immutable: they can only be set once during
-     * construction.
+     * @dev Sets the initial values the internal delay and {owner}.
+     * 
+     * The `delay` value is immutable. It can only be set at the constructor.
      */
-    constructor(uint48 initialDelay, address initialAdmin) {
-        _delay = initialDelay;
+    constructor(uint48 delay, address initialAdmin) {
+        _delay = delay;
         _grantRole(DEFAULT_ADMIN_ROLE, initialAdmin);
     }
 

contracts/access/README.adoc

@@ -23,3 +23,7 @@ This directory provides ways to restrict who can access the functions of a contr
 {{IAccessControlEnumerable}}
 
 {{AccessControlEnumerable}}
+
+{{IAccessControlAdminRules}}
+
+{{AccessControlAdminRules}}

docs/modules/ROOT/pages/access-control.adoc

@@ -131,6 +131,8 @@ Every role has an associated admin role, which grants permission to call the `gr
 
 This mechanism can be used to create complex permissioning structures resembling organizational charts, but it also provides an easy way to manage simpler applications. `AccessControl` includes a special role, called `DEFAULT_ADMIN_ROLE`, which acts as the **default admin role for all roles**. An account with this role will be able to manage any other role, unless `_setRoleAdmin` is used to select a new admin role.
 
+NOTE: For risk mitigations related to `DEFAULT_ADMIN_ROLE` management. See xref:api:access.adoc#AccessControlAdminRules[`AccessControlAdminRules`] as an alternative with restrictions such as 2-step admin role change, single-holder enforcing and configurable minimum delay.
+
 Let's take a look at the ERC20 token example, this time taking advantage of the default admin role:
 
 [source,solidity]