Update upgrade docs

docs/modules/ROOT/nav.adoc

@@ -1,7 +1,8 @@
 * xref:index.adoc[Overview]
-* xref:wizard.adoc[Wizard]
-* xref:extensibility.adoc[Extensibility]
-* xref:upgrades.adoc[Upgradeability]
+//* xref:wizard.adoc[Wizard]
+//* xref:extensibility.adoc[Extensibility]
+* xref:interfaces.adoc[Interfaces and Dispatchers]
+* xref:upgrades.adoc[Upgrades]
 ** xref:/api/upgrades.adoc[API Reference]
 
 * xref:accounts.adoc[Accounts]
@@ -16,12 +17,12 @@
 // ** xref:erc721.adoc[ERC721]
 // ** xref:erc1155.adoc[ERC1155]
 
-* xref:security.adoc[Security]
+// * xref:security.adoc[Security]
 
 * xref:introspection.adoc[Introspection]
 ** xref:/api/introspection.adoc[API Reference]
 
-* xref:udc.adoc[Universal Deployer Contract]
-* xref:utilities.adoc[Utilities]
+// * xref:udc.adoc[Universal Deployer Contract]
+// * xref:utilities.adoc[Utilities]
 
 * xref:contracts::index.adoc[Contracts for Solidity]

docs/modules/ROOT/pages/access.adoc

@@ -28,7 +28,7 @@ xref:/api/access.adoc#AccessControl-initializer[`initializer`] like this:
 use openzeppelin::access::ownable::Ownable;
 
 #[starknet::contract]
-mod Contract {
+mod MyContract {
     use starknet::ContractAddress;
     use super::Ownable;
 
@@ -50,7 +50,7 @@ To restrict a function's access to the owner only, add in the `assert_only_owner
 [,javascript]
 ----
 #[starknet::contract]
-mod Contract {
+mod MyContract {
     use openzeppelin::access::ownable::Ownable;
 
     (...)
@@ -68,7 +68,7 @@ mod Contract {
 
 === Interface
 
-This is the full interface a contract must implement to be compliant with the `Ownable` implementation:
+This is the full interface of the `Ownable` implementation:
 
 [,javascript]
 ----
@@ -123,7 +123,7 @@ and sets a 'minter' role:
 const MINTER_ROLE: felt252 = selector!('MINTER_ROLE');
 
 #[starknet::contract]
-mod Contract {
+mod MyContract {
     use openzeppelin::access::accesscontrol::AccessControl::InternalImpl::assert_only_role;
     use openzeppelin::access::accesscontrol::AccessControl;
     use openzeppelin::token::erc20::ERC20;
@@ -184,7 +184,7 @@ const MINTER_ROLE: felt252 = selector!('MINTER_ROLE');
 const BURNER_ROLE: felt252 = selector!('BURNER_ROLE');
 
 #[starknet::contract]
-mod Contract {
+mod MyContract {
     use openzeppelin::access::accesscontrol::AccessControl::InternalImpl::assert_only_role;
     use openzeppelin::access::accesscontrol::AccessControl;
     use openzeppelin::token::erc20::ERC20;
@@ -284,7 +284,7 @@ const MINTER_ROLE: felt252 = selector!('MINTER_ROLE');
 const BURNER_ROLE: felt252 = selector!('BURNER_ROLE');
 
 #[starknet::contract]
-mod Contract {
+mod MyContract {
     use openzeppelin::access::accesscontrol::AccessControl::InternalImpl::assert_only_role;
     use openzeppelin::access::accesscontrol::AccessControl;
     use openzeppelin::access::accesscontrol::DEFAULT_ADMIN_ROLE;
@@ -388,7 +388,7 @@ TIP: The `selector!` macro can be used to compute {sn_keccak} in Cairo.
 
 === Interface
 
-This is the full interface a contract must implement to be compliant with the `AccessControl` implementation:
+This is the full interface of the `AccessControl` implementation:
 
 [,javascript]
 ----

docs/modules/ROOT/pages/api/access.adoc

@@ -2,15 +2,15 @@
 :AccessControl: xref:AccessControl[AccessControl]
 :Ownable: xref:Ownable[Ownable]
 :src5: https://github.com/starknet-io/SNIPs/blob/main/SNIPS/snip-5.md[SRC5]
-:inner-src5: xref:api/introspection.adoc#ISRC5[SRC5]
+:inner-src5: xref:api/introspection.adoc#ISRC5[SRC5 ID]
 :_set_role_admin: xref:#AccessControl-_set_role_admin[_set_role_admin]
 
 = Access Control
 
 This directory provides ways to restrict who can access the functions of a contract or when they can do it.
 
-- {Ownable} is a simple mechanism with a single owner "role" that can be assigned to a single account.
-This mechanism can be useful for quick tests but projects with production concerns are likely to outgrow it.
+- {Ownable} is a simple mechanism with a single "owner" role that can be assigned to a single account.
+This mechanism can be useful in simple scenarios, but fine grained access needs are likely to outgrow it.
 - {AccessControl} provides a general role based access control mechanism. Multiple hierarchical roles can be created and
 assigned each to multiple accounts.
 
@@ -24,18 +24,10 @@ assigned each to multiple accounts.
 use openzeppelin::access::ownable::Ownable;
 ```
 
-Contract module which provides a basic access control mechanism, where
-there is an account (an owner) that can be granted exclusive access to
-specific functions.
+`Ownable` provides a basic access control mechanism where an account
+ (an owner) can be granted exclusive access to specific functions.
 
-This module provides an internal utility named `assert_only_owner`, which can be applied to your functions
-to restrict their use to the owner.
-
-[.contract-index]
-.Utilities
---
-* xref:Ownable-assert_only_owner[`++InternalImpl::assert_only_owner(self)++`]
---
+This module includes the `assert_only_owner` internal to restrict a function to be used only by the owner.
 
 [.contract-index]
 .External Functions
@@ -44,8 +36,8 @@ to restrict their use to the owner.
 .OwnableImpl
 
 * xref:Ownable-owner[`++owner(self)++`]
-* xref:Ownable-renounce_ownership[`++renounce_ownership(self)++`]
 * xref:Ownable-transfer_ownership[`++transfer_ownership(self, new_owner)++`]
+* xref:Ownable-renounce_ownership[`++renounce_ownership(self)++`]
 --
 
 [.contract-index]
@@ -56,6 +48,7 @@ to restrict their use to the owner.
 
 * xref:Ownable-initializer[`++initializer(self, owner)++`]
 * xref:Ownable-_transfer_ownership[`++_transfer_ownership(self, new_owner)++`]
+* xref:Ownable-assert_only_owner[`++assert_only_owner(self)++`]
 --
 
 [.contract-index]
@@ -64,24 +57,24 @@ to restrict their use to the owner.
 * xref:Ownable-OwnershipTransferred[`++OwnershipTransferred(previous_owner, new_owner)++`]
 --
 
-[#Ownable-Utilities]
-==== Utilities
-
-[.contract-item]
-[[Ownable-assert_only_owner]]
-==== `[.contract-item-name]#++assert_only_owner++#++(self: @ContractState)++` [.item-kind]#internal#
-
-Panics if called by any account other than the owner.
-
-[#Ownable-Functions]
-==== Functions
+[#Ownable-External-Functions]
+==== External Functions
 
 [.contract-item]
 [[Ownable-owner]]
 ==== `[.contract-item-name]#++owner++#++(self: @ContractState) → ContractAddress++` [.item-kind]#external#
 
 Returns the address of the current owner.
 
+[.contract-item]
+[[Ownable-transfer_ownership]]
+==== `[.contract-item-name]#++transfer_ownership++#++(ref self: ContractState, new_owner: ContractAddress)++` [.item-kind]#external#
+
+Transfers ownership of the contract to a new account (`new_owner`).
+Can only be called by the current owner.
+
+Emits an xref:Ownable-OwnershipTransferred[OwnershipTransferred] event.
+
 [.contract-item]
 [[Ownable-renounce_ownership--]]
 ==== `[.contract-item-name]#++renounce_ownership++#++(ref self: ContractState)++` [.item-kind]#external#
@@ -92,14 +85,8 @@ Leaves the contract without owner. It will not be possible to call
 NOTE: Renouncing ownership will leave the contract without an owner,
 thereby removing any functionality that is only available to the owner.
 
-[.contract-item]
-[[Ownable-transfer_ownership]]
-==== `[.contract-item-name]#++transfer_ownership++#++(ref self: ContractState, new_owner: ContractAddress)++` [.item-kind]#external#
-
-Transfers ownership of the contract to a new account (`new_owner`).
-Can only be called by the current owner.
-
-Emits an xref:Ownable-OwnershipTransferred[OwnershipTransferred] event.
+[#Ownable-Internal-Functions]
+==== Internal Functions
 
 [.contract-item]
 [[Ownable-initializer]]
@@ -118,6 +105,12 @@ Internal function without access restriction.
 
 Emits an xref:Ownable-OwnershipTransferred[OwnershipTransferred] event.
 
+[.contract-item]
+[[Ownable-assert_only_owner]]
+==== `[.contract-item-name]#++assert_only_owner++#++(self: @ContractState)++` [.item-kind]#internal#
+
+Panics if called by any account other than the owner.
+
 [#Ownable-Events]
 ==== Events
 
@@ -144,7 +137,7 @@ use openzeppelin::access::accesscontrol::interface::IAccessControl;
 External interface of AccessControl.
 
 [.contract-index]
-.{inner-src5} ID
+.{inner-src5}
 --
 0x23700be02858dbe2ac4dc9c9f66d0b6b0ed81ec7f970ca6844500a56ff61751
 --
@@ -277,8 +270,7 @@ Roles are referred to by their `felt252` identifier:
 
 ```javascript
 // sn_keccak('MY_ROLE')
-const MY_ROLE: felt252 =
-    0x3c877e40edb41710f0baf588c878ee15a04499b06ae8c98cf488875d91a7213;
+const MY_ROLE: felt252 = selector!('MY_ROLE');
 ```
 
 Roles can be used to represent a set of permissions. To restrict access to a
@@ -312,12 +304,6 @@ 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.
 
-[.contract-index]
-.Utilities
---
-* xref:#AccessControl-assert_only_role[`++InternalImpl::assert_only_role(self, role)++`]
---
-
 [.contract-index]
 .External Functions
 --
@@ -345,6 +331,7 @@ accounts that have been granted it.
 * xref:#AccessControl-_set_role_admin[`++_set_role_admin(self, role, admin_role)++`]
 * xref:#AccessControl-_grant_role[`++_grant_role(self, role, account)++`]
 * xref:#AccessControl-_revoke_role[`++_revoke_role(self, role, account)++`]
+* xref:#AccessControl-assert_only_role[`++assert_only_role(self, role)++`]
 --
 
 [.contract-index]
@@ -357,17 +344,8 @@ accounts that have been granted it.
 * xref:#AccessControl-RoleRevoked[`++RoleRevoked(role, account, sender)++`]
 --
 
-[#AccessControl-Utilities]
-==== Utilities
-
-[.contract-item]
-[[AccessControl-assert_only_role]]
-==== `[.contract-item-name]#++assert_only_role++#++(self: @ContractState, role: felt252)++` [.item-kind]#internal#
-
-Panics if called by any account without the given `role`.
-
-[#AccessControl-Functions]
-==== Functions
+[#AccessControl-External-Functions]
+==== External Functions
 
 [.contract-item]
 [[AccessControl-has_role]]
@@ -438,6 +416,9 @@ May emit a {RoleRevoked} event.
 
 See xref:api/introspection.adoc#ISRC5-supports_interface[ISRC5::supports_interface].
 
+[#AccessControl-Internal-Functions]
+==== Internal Functions
+
 [.contract-item]
 [[AccessControl-initializer]]
 ==== `[.contract-item-name]#++initializer++#++(ref self: ContractState)++` [.item-kind]#internal#
@@ -472,6 +453,12 @@ Internal function without access restriction.
 
 May emit a {RoleRevoked} event.
 
+[.contract-item]
+[[AccessControl-assert_only_role]]
+==== `[.contract-item-name]#++assert_only_role++#++(self: @ContractState, role: felt252)++` [.item-kind]#internal#
+
+Panics if called by any account without the given `role`.
+
 [#AccessControl-Events]
 ==== Events