HackMDHolochain API Documentation Checklist
Crate level
Standards for crate level documentation
- Brief explanation of the crates intention.
- Minimal example that shows its use in context.
- List of links to all important modules and types with brief a description.
Use the rust paths style of linking in docs eg:
[ValidatingLinkDefinition](entry_definition::ValidatingLinkDefinition) - Provide links to learning resources like tutorials, examples, and install guide.
Module level
Give a broader context and avoid details.
- High level broad overview of the module that gives context to the types.
- Provide example of how this module is used.
- Doc comments are
//!style.
Type / function level
Explain the precise details.
- Each type / function contains a concise sentence explaining what it does.
- Reader can understand type without needing other references.
- Provide examples for really common use items.
- Enum variants are documented unless the name is really obvious.
- Doc comments are
///style. - Functions include a brief description of
Errors,PanicsandUnsafewhen relevant. - Use
pub(crate)for things that don't need to be completely public.
Examples
- Hide unnecessary code from examples like:
# use std::path::Path; // This line will be hidden
let path = Path::new("some/path"); // This line will be visible
- Examples use
?nottry!orunwraporexpect.
Testing
- All examples pass
cargo test.
Release notes
- Include code examples when a breaking change occurs.
Example of well written release notes.
