Improve documentation

[joshlf]

This issue tracks improvements to our documentation. See our roadmap for the high-level vision that the tasks tracked here fit into.

Top-level docs

Framing

• 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.
• 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)
• 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 and offered that we can incorporate it into our docs; it includes a lot of good examples and explanations

[tim-seoss]

Whilst this is a big task, a couple of examples¹ would probably go a long way to helping newcomers to zerocopy.

At its very simplest, it could take the form of a series of links to other repositories, each of which shows usage zerocopy in a common/canonical way.

If you could point me to an example or any notes or other resources for packet serialisation I'd be happy to try and knock something up and crate a PR.

Footnotes

1. OK, there are already a couple of examples, but they are two slight variants of the same code - one in src/byteorder.rs at line 33 and the other in src/lib.rs at line 1482, and the example is UDP packet parsing/deserialisation - there are no examples at all of the sort of overview of code flow which is suitable for serialisation e.g. packet assembly example with header+body+footer ↩

[joshlf]

Thanks for offering to help, @tim-seoss! I unfortunately don't have time to help with this right now, but I'll let you know when I do 🙂

[joshlf]

Hey @tim-seoss, still don't have a ton of time to devote to mentoring this, but I realized that I could at least point you to some locations that have a lot of zerocopy uses you could take a look at. If you're interested in writing these up, I'd suggest at least pinging this thread first to confirm that a given example uses a pattern/style we'd like to encourage.

These are both in Fuchsia; the latter is specifically a packet parsing/serializing library, so it's got a lot of more gnarly uses of zerocopy. I'd just use the search function to search for "zerocopy" or the names of individual types, and that'll be a good starting point.

• https://cs.opensource.google/fuchsia/fuchsia/+/main:src/
• https://cs.opensource.google/fuchsia/fuchsia/+/main:src/connectivity/lib/packet-formats/