docs: Add comprehensive documentation for custom EnumerableSet

contracts/src/utils/structs/enumerable_set/mod.rs

@@ -1,14 +1,58 @@
 //! Smart contract for managing sets.
+//!
+//! Sets have the following properties:
+//!
+//! * Elements are added, removed, and checked for existence in constant time
+//!   (O(1)).
+//! * Elements are enumerated in O(n). No guarantees are made on the ordering.
+//! * Set can be cleared (all elements removed) in O(n).
+//!
+//! [`EnumerableSet`] provides a generic implementation of sets that can store
+//! various data types including [`alloy_primitives::Address`],
+//! [`alloy_primitives::B256`], [`alloy_primitives::U8`],
+//! [`alloy_primitives::U16`], [`alloy_primitives::U32`],
+//! [`alloy_primitives::U64`], [`alloy_primitives::U128`], and [`U256`].
+//!
+//! # Usage Example
+//!
+//! ```rust,ignore
+//! use alloy_primitives::Address;
+//! use openzeppelin_stylus::utils::structs::enumerable_set::EnumerableSet;
+//! use stylus_sdk::prelude::*;
+//!
+//! #[storage]
+//! pub struct MyContract {
+//!     members: EnumerableSet<Address>,
+//! }
+//!
+//! impl MyContract {
+//!     pub fn add_member(&mut self, member: Address) -> bool {
+//!         self.members.add(member)
+//!     }
+//!
+//!     pub fn remove_member(&mut self, member: Address) -> bool {
+//!         self.members.remove(member)
+//!     }
+//!
+//!     pub fn is_member(&self, member: Address) -> bool {
+//!         self.members.contains(member)
+//!     }
+//! }
+//! ```
+//!
+//! # Custom Storage Types
+//!
+//! You can implement [`EnumerableSet`] for your own storage types by
+//! implementing the [`Element`] and [`Accessor`] traits (see [`element`]
+//! module). This allows you to create sets of custom data structures that
+//! integrate seamlessly with Stylus storage.
+//!
+//! **Note**: [`stylus_sdk::storage::StorageBytes`] and
+//! [`stylus_sdk::storage::StorageString`] cannot currently be implemented due
+//! to current Stylus SDK limitations, but this might change in the future.
 
 pub mod element;
 
-/// Sets have the following properties:
-///
-/// * Elements are added, removed, and checked for existence in constant
-///   time (O(1)).
-/// * Elements are enumerated in O(n). No guarantees are made on the
-///   ordering.
-/// * Set can be cleared (all elements removed) in O(n).
 use alloc::{vec, vec::Vec};
 
 use alloy_primitives::{uint, U256};

docs/modules/ROOT/nav.adoc

@@ -20,3 +20,4 @@
 ** xref:uups-proxy.adoc[UUPS Proxy]
 
 * xref:utilities.adoc[Utilities]
+** xref:enumerable-set-custom.adoc[Custom EnumerableSet Implementation]