google / google/zerocopy

Improve documentation

Open
#32 3 comments 0 reactions 0 assignees View on GitHub
compatibility-nonbreaking
Dominant language
Rust
Stars
2.6k
Forks
179
Avg merge
1d 19h
Merged PRs (30d)
29

Description

This issue tracks improvements to our documentation. See [our roadmap](https://github.com/google/zerocopy/issues/98) for the high-level vision that the tasks tracked here fit into.

# Top-level docs

## Framing

- [x] ~~Documentation frames zerocopy as a general-purpose tool for replacing unsafe code, not just as a tool for parsing or another specific task.~~ Done in [#386](https://github.com/google/zerocopy/pull/386).
- [ ] Consider adding examples of domains in which zerocopy is used in order to convey the breadth of use cases and suggest that it's not primarily meant for any single use case

## Use cases

- [ ] Top-level documentation points users in the right direction for most common use cases
- This documentation must not assume a familiarity with unsafe code, but should instead focus on use cases

## Correctness and soundness

- [ ] Documentation frames the "unsafe as the cryptography of the Rust world" idea
- [ ] Documentation describes zerocopy's future-soundness guarantee
- [ ] Documentation describes the steps we take to ensure soundness
- [ ] Safety/soundness arguments, especially with regards to reasoning only in terms of documented guarantees by the language reference or the standard library documentation
- [ ] All tests run under Miri, including under experimental memory models (currently: stacked borrows, tree borrows, and strict provenance)
- [ ] Once we use them, mention formal modeling tools ([#378](https://github.com/google/zerocopy/issues/378))
- [ ] Consider citing high-profile users who are comfortable with this

# Module/item docs

- [ ] Items (types, methods, etc) provide toy examples to demonstrate basic usage
- [ ] Modules and items whose usage is not self-evident provide more involved examples that help to teach users the correct mental model
- [ ] Modules and items call out common use cases that would be reasonable to solve using them
- [ ] Modules and items call out common use cases that would _not_ be reasonable to solve using them, but which it would be easy to mistakenly believe would be reasonable to solve using them (e.g., `FromBytes` for parsing without considering endiannness)

# Miscellaneous

- [ ] Fully-fledged implementation examples in a separate module or in the `examples` directory

@kupiakos has provided [this writeup](https://gist.github.com/kupiakos/a9f76ce07e7a38a17ebb88534a475b2b) and offered that we can incorporate it into our docs; it includes a lot of good examples and explanations

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.