Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Migrate Precompiles chapter to inline .sol API docs #243

Merged
merged 2 commits into from
Jan 23, 2024

Conversation

matevz
Copy link
Member

@matevz matevz commented Dec 13, 2023

  • migrates https://docs.oasis.io/dapp/sapphire/precompiles to .sol files viewable on https://api.docs.oasis.io
  • makes all natspec documentation consistent accross .sol files:
    • always use @notice to describe what the function does so the comment is included in the API reference
    • optionally extend the the description above with implementation details using the @dev directive
  • workaround for Doc generator strips all white spaces from comments foundry-rs/foundry#6619:
    • moves the initial example from Sapphire.sol to README.md because forge doc removes indentation
    • flattens two-level bullets and replaces it with subsubsubsubheaders instead
    • introduce subsubsubheaders when paragraphs really needed
  • adds per-page TOC (requires cargo install mdbook-pagetoc), updated CI, README and packages.json accordingly

For preview

cd contracts
cargo install mdbook-pagetoc
pnpm doc

And open contracts/sol/sapphire-contracts/book/index.html in a browser.

@matevz matevz force-pushed the matevz/docs/migrate-precompiles-to-sol branch 3 times, most recently from 16d8498 to 13601f3 Compare December 18, 2023 15:51
@matevz matevz marked this pull request as ready for review December 18, 2023 15:52
@matevz matevz force-pushed the matevz/docs/migrate-precompiles-to-sol branch 2 times, most recently from 2b6ba11 to 864c52f Compare December 19, 2023 16:47
@matevz matevz force-pushed the matevz/docs/migrate-precompiles-to-sol branch 4 times, most recently from 760d6c7 to 0b190eb Compare December 20, 2023 15:48
@matevz matevz force-pushed the matevz/docs/migrate-precompiles-to-sol branch from 0b190eb to 31ce92d Compare January 22, 2024 12:45
@matevz matevz requested a review from CedarMist January 22, 2024 12:48
@matevz matevz force-pushed the matevz/docs/migrate-precompiles-to-sol branch 6 times, most recently from 957ae3c to cfaf8d1 Compare January 23, 2024 12:32
@matevz matevz force-pushed the matevz/docs/migrate-precompiles-to-sol branch 3 times, most recently from 1fe17c8 to 24d2b08 Compare January 23, 2024 12:48
@matevz matevz force-pushed the matevz/docs/migrate-precompiles-to-sol branch from 24d2b08 to a679e05 Compare January 23, 2024 12:48
@matevz matevz merged commit 8630a20 into main Jan 23, 2024
14 checks passed
@matevz matevz deleted the matevz/docs/migrate-precompiles-to-sol branch January 23, 2024 12:57
github-actions bot added a commit that referenced this pull request Jan 23, 2024
…tevz/docs/migrate-precompiles-to-sol

docs: Migrate Precompiles chapter to inline .sol API docs 8630a20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants