docs: Improve README with comprehensive examples and add NatSpec comm…#84
Open
phessophissy wants to merge 1 commit intobuttonwood-protocol:mainfrom
Open
docs: Improve README with comprehensive examples and add NatSpec comm…#84phessophissy wants to merge 1 commit intobuttonwood-protocol:mainfrom
phessophissy wants to merge 1 commit intobuttonwood-protocol:mainfrom
Conversation
…ents ## README.md Improvements - Added badges (License, Solidity version, Hardhat) - Added Table of Contents for easy navigation - Added Overview section explaining ButtonToken vs UnbuttonToken - Added Installation and Quick Start guides - Added Contract Architecture diagram - Added 5 comprehensive usage examples: 1. Wrapping ETH into ButtonWETH via Router 2. Depositing into ButtonToken directly 3. Using UnbuttonToken for rebasing assets 4. Creating new ButtonToken via Factory 5. TypeScript integration example - Added API Reference tables for both contracts - Added Security section with known limitations - Added structured Deployments table - Improved Contributing guidelines ## ButtonToken.sol NatSpec Improvements - Added comprehensive contract-level documentation - Added @title, @author, @notice, @dev tags - Documented mathematical model (bits system) - Added accounting guarantees documentation - Enhanced all public function documentation with: - @notice for user-facing description - @dev for technical details - @param for all parameters - @return for return values - @Custom:example with code samples - Requirements and Effects sections - Documented all private helper functions - Added security notes and emits documentation ## UnbuttonToken.sol NatSpec Improvements - Added comprehensive contract-level documentation - Documented share-based mathematical model - Added use cases (DeFi, Portfolio, Yield Farming) - Added security considerations for overflow limits - Enhanced all public function documentation - Added @Custom:formula tags for calculations - Documented initialization security (anti-manipulation) - Added code examples for common operations This contribution addresses documentation improvements as identified in the repository's open issues.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
This PR significantly improves the project documentation by enhancing the README with comprehensive examples and adding detailed NatSpec comments to the core contracts.
Type of Change
Changes Made
README.md
ButtonToken.sol
@title,@author,@notice,@devcontract-level docs@custom:examplecode snippetsUnbuttonToken.sol
@custom:formulatags for calculationsMotivation and Context
Good documentation is essential for developer adoption. These improvements will:
How Has This Been Tested?
No logic changes were made - documentation only. Existing tests should pass without modification.
Checklist
Screenshots (if applicable)
N/A - Documentation changes only
Additional Notes
This contribution addresses documentation improvements as noted in the repository's contribution guidelines.