Update EIP-7201: Updates to wording

Merged by EIP-Bot.

EIPS/eip-7201.md

@@ -1,7 +1,7 @@
 ---
 eip: 7201
 title: Namespaced Storage Layout
-description: A formula for the storage location of structs in the namespaced storage pattern.
+description: Conventions for the storage location of structs in the namespaced storage pattern.
 author: Francisco Giordano (@frangio), Hadrien Croubois (@Amxx), Ernesto García (@ernestognw), Eric Lau (@ericglau)
 discussions-to: https://ethereum-magicians.org/t/eip-7201-namespaced-storage-layout/14796
 status: Review
@@ -12,7 +12,7 @@ created: 2023-06-20
 
 ## Abstract
 
-We define a formula to derive a location in storage, that is suitable for structs of arbitrary size, from an identifier. The formula is chosen to be safe against collisions with the storage layouts used by Solidity and Vyper. We define a convention to document this location in Solidity source code.
+We define the NatSpec annotation `@custom:storage-location` to document storage namespaces and their location in storage in Solidity or Vyper source code. Additionally, we define a formula to derive a location from an arbitrary identifier. The formula is chosen to be safe against collisions with the storage layouts used by Solidity and Vyper.
 
 ## Motivation
 
@@ -24,12 +24,18 @@ These storage usage patterns are invisible to the Solidity and Vyper compilers b
 
 ## Specification
 
+### Preliminaries
+
 A _namespace_ consists of a set of ordered variables, some of which may be dynamic arrays or mappings, with its values laid out following the same rules as the default storage layout but rooted in some location that is not necessarily slot 0. A contract using namespaces to organize storage is said to use _namespaced storage_.
 
 A _namespace id_ is a string that identifies a namespace in a contract. It should not contain any whitespace characters.
 
+### `@custom:storage-location`
+
 A namespace in a contract should be implemented as a struct type. These structs should be annotated with the NatSpec tag `@custom:storage-location <FORMULA_ID>:<NAMESPACE_ID>`, where `<FORMULA_ID>` identifies a formula used to compute the storage location where the namespace is rooted, based on the namespace id. _(Note: The Solidity compiler includes this annotation in the AST since v0.8.20, so this is recommended as the minimum compiler version when using this pattern.)_ Structs with this annotation found outside of contracts are not considered to be namespaces for any contract in the source code.
 
+### Formula
+
 The formula identified by `erc7201` is defined as `erc7201(id: string) = keccak256(keccak256(id) - 1) & ~0xff`. In Solidity, this corresponds to the expression `keccak256(abi.encode(uint256(keccak256(id)) - 1)) & ~bytes32(uint256(0xff))`. When using this formula the annotation becomes `@custom:storage-location erc7201:<NAMESPACE_ID>`. For example, `@custom:storage-location erc7201:foobar` annotates a namespace with id `"foobar"` rooted at `erc7201("foobar")`.
 
 Future EIPs may define new formulas with unique formula identifiers. It is recommended to follow the convention set in this EIP and use an identifier of the format `erc1234`.