# Holochain 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`, `Panics` and `Unsafe` when 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 `?` not `try!` or `unwrap` or `expect`.

## Testing
- [ ] All examples pass `cargo test`.

## Release notes
- [ ] Include code examples when a breaking change occurs.
[Example][release] of well written release notes.

## Good examples of docs
- [csv](https://docs.rs/csv/1.1.1/csv/)
- [hashbrown](https://docs.rs/hashbrown/0.5.1/hashbrown/struct.HashMap.html)
- [quote](https://docs.rs/quote/0.6.13/quote/)
- [serde_json](https://docs.serde.rs/serde_json/)
- [log](https://docs.rs/log/0.4.8/log/)
- [regex](https://docs.rs/regex/1.2.1/regex/)

## Additional Resources
- [List of conventions](https://rust-lang.github.io/rfcs/1574-more-api-documentation-conventions.html#appendix-a-full-conventions-text)
- [Example of good conventions](https://rust-lang.github.io/rfcs/1574-more-api-documentation-conventions.html#example-1)

[ref]: https://rust-lang.github.io/rfcs/1574-more-api-documentation-conventions.html#link-all-the-things-1
[howto-link]: https://rust-lang-nursery.github.io/api-guidelines/documentation.html#prose-contains-hyperlinks-to-relevant-things-c-link
[release]: https://github.com/serde-rs/serde/releases/tag/v1.0.0