docs: Add comprehensive documentation for custom EnumerableSet #797
Conversation
…entation - Add detailed module documentation with usage examples for EnumerableSet - Create comprehensive Antora documentation guide for custom types - Include step-by-step implementation instructions for Element and Accessor traits - Provide complete working examples with custom UserId and ProductId types - Document built-in support for Address, B256, and integer types - Add best practices, gas considerations, and testing guidance - Update navigation structure and cross-references - Document current limitations with StorageBytes and StorageString Addresses issue OpenZeppelin#761 by providing clear examples and docs for implementing EnumerableSet with user-defined storage types in Stylus.
sumitvekariya
requested review from
bidzyyys,
qalisander and
0xNeshi
as code owners
❌ Deploy Preview for contracts-stylus failed. Why did it fail? →
|
| //! #[storage] | ||
| //! pub struct MyContract { | ||
| //! members: EnumerableSet<Address>, | ||
| //! } | ||
| //! | ||
| //! impl MyContract { |
There was a problem hiding this comment.
| //! #[storage] | |
| //! pub struct MyContract { | |
| //! members: EnumerableSet<Address>, | |
| //! } | |
| //! | |
| //! impl MyContract { | |
| //! #[storage] | |
| //! #[entrypoint] | |
| //! pub struct MyContract { | |
| //! members: EnumerableSet<Address>, | |
| //! } | |
| //! | |
| //! #[public] | |
| //! impl MyContract { |
Let's have a complete deployable contract
| @@ -49,3 +49,5 @@ Contracts for Stylus provides these libraries for enhanced data structure manage | |||
| - https://docs.rs/openzeppelin-stylus/0.3.0-rc.1/openzeppelin_stylus/utils/structs/bitmap/index.html[`BitMaps`]: Store packed booleans in storage. | |||
| - https://docs.rs/openzeppelin-stylus/0.3.0-rc.1/openzeppelin_stylus/utils/structs/checkpoints/index.html[`Checkpoints`]: Checkpoint values with built-in lookups. | |||
| - https://docs.rs/openzeppelin-stylus/0.3.0-rc.1/openzeppelin_stylus/utils/structs/enumerable_set/index.html[`EnumerableSets`]: Contract for managing sets of many primitive types. | |||
|
|
|||
| For detailed guidance on implementing EnumerableSet with custom storage types, see xref:enumerable-set-custom.adoc[Custom EnumerableSet Implementation]. | |||
There was a problem hiding this comment.
remove docs/pnpm-lock.yaml
| //! 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). |
There was a problem hiding this comment.
Move these docs above the EnumerableSet struct.
Looking at it from dev perspective, hovering over the EnumerableSet struct I'm about to use, I'd expect it to contain docs explaining how to use it. There's a high chance devs would not know they need to hover over the module to get an example usage.
|
I just noticed that another contributor was already assigned to this issue and had already created a draft PR, with just as good docs as in this PR. We appreciate your effort on the PR, but to avoid more duplicate work for both you and them, and to avoid redundant reviews for us maintainers, we will need to close this PR. We generally assign issues to specific contributors exactly to avoid these types of situations. For future reference, if you'd like to work on an already assigned issue, please ping us before starting any work, asking if you can take over the issue. Maybe the current assignee is inactive or their contribution is low quality, so we determine that it's better to reassign the issue to you. |
Hey I totally get it, I usually take up the issues which are unassigned or assigned(long before but not actively worked upon) ones. But this one I completely missed that it had a PR drafted already, my bad. Will ask to be assigned befor start working on already assigned issues. Thanks for pointing out. |
Description
This PR addresses issue #761 by adding comprehensive documentation for implementing custom
EnumerableSettypes in Stylus contracts.Changes Made
Enhanced EnumerableSet Module Documentation
EnumerableSet<Address>example showing basic usage patternsElementandAccessortraitsStorageBytesandStorageStringCreated Comprehensive Antora Documentation
docs/modules/ROOT/pages/enumerable-set-custom.adocUserIdandProductIdtypesUpdated Navigation and Cross-References
docs/modules/ROOT/nav.adocdocs/modules/ROOT/pages/utilities.adocwith cross-reference to new guideAddressed Current Limitations
StorageBytesandStorageStringcannot currently be implemented due to Stylus SDK limitationsTesting
npm run docsRelated Issues
Closes #761
Notes
This implementation provides developers with clear, comprehensive guidance on:
The documentation includes complete, working code examples that developers can copy and adapt for their own use cases.