cairo-contracts
cairo-contracts copied to clipboard
OpenZeppelin
Write down docs styleguide
- avoid talking about "us", or the writer as much as possible
- don’t capitalize Account unless it’s a specific contract/impl
- Don't include argument types in the header sections for
Utilities,Functions, andEvents, in the API Reference.
- Write the casing name in the casing style e.g. camelCase, snake_case, PascalCase, etc
-
Write all non-H1 headings in sentence case (only capitalize the first word and proper nouns)
- For the record, I disagree with this approach. I instead vote for title case in all doc headings because:
- Titles of sections are, well, titles and titles should be capitalized IMO.
- Consistency with OZ Solidity docs.
- For the record, I disagree with this approach. I instead vote for title case in all doc headings because:
Use "panics" instead of "reverts" or "throws" since it's the appropriate term in Starknet.
Add / at the end of directory names to highlight it's a directory. e.g.: my_folder/ instead of my_folder
Always scope IDs by the module name in API Reference. Under the ERC20 module section, the name() function should have the ID: ERC20-name
Words in html IDs (adoc pages) must be separated by dashes: ERC20-name instead of ERC20::name
Write all non-H1 headings in sentence case (only capitalize the first word and proper nouns)
For the record, I disagree with this approach. I instead vote for title case in all doc headings because:
- Titles of sections are, well, titles and titles should be capitalized IMO.
- Consistency with OZ Solidity docs.
where does this rule come from, if you disagree with it?
Always scope IDs by the module name in API Reference. Under the
ERC20module section, thename()function should have the ID:ERC20-name
what do you mean by scope IDs? is this an ascii doc thing?
Write all non-H1 headings in sentence case (only capitalize the first word and proper nouns)
- For the record, I disagree with this approach. I instead vote for title case in all doc headings because:
- Titles of sections are, well, titles and titles should be capitalized IMO.
- Consistency with OZ Solidity docs.
where does this rule come from, if you disagree with it?
It's just how the old and forthcoming docs are currently written. There's no rule that I'm aware of
what do you mean by scope IDs? is this an ascii doc thing?
The ID of the HTML section generated from the adoc file, should be scoped by the module name: have this #Account-supports_interface, instead of just #supports_interface.
[.contract-item]
[[Account-supports_interface]]
...
Put SRC5 ID block as a section (similar to Functions and Events) on top at the Interfaces where the ID is usually exposed.
Opened the "Consider documenting asserts/guards" discussion separately in its own thread: #745