[docs] Improve crate-level docs (#386)

Release 0.7.5

Cargo.toml

@@ -5,13 +5,13 @@
 # Put both crates in a single workspace so that `trybuild` compiler errors have
 # paths that are stable regardless of the path to the repository root. This
 # avoids issues like:
-# https://github.com/dtolnay/trybuild/issues/207#issuecomment-1312277494
+# https://github.com/dtolnay/trybuild/issues/207#issuecomment-131227.594
 [workspace]
 
 [package]
 edition = "2021"
 name = "zerocopy"
-version = "0.7.4"
+version = "0.7.5"
 authors = ["Joshua Liebow-Feeser <[email protected]>"]
 description = "Utilities for zero-copy parsing and serialization"
 license = "BSD-2-Clause"
@@ -41,7 +41,7 @@ simd-nightly = ["simd"]
 __internal_use_only_features_that_work_on_stable = ["alloc", "derive", "simd"]
 
 [dependencies]
-zerocopy-derive = { version = "=0.7.4", path = "zerocopy-derive", optional = true }
+zerocopy-derive = { version = "=0.7.5", path = "zerocopy-derive", optional = true }
 
 [dependencies.byteorder]
 version = "1.3"
@@ -52,7 +52,7 @@ optional = true
 # zerocopy-derive remain equal, even if the 'derive' feature isn't used.
 # See: https://github.com/matklad/macro-dep-test
 [target.'cfg(any())'.dependencies]
-zerocopy-derive = { version = "=0.7.4", path = "zerocopy-derive" }
+zerocopy-derive = { version = "=0.7.5", path = "zerocopy-derive" }
 
 [dev-dependencies]
 assert_matches = "1.5"
@@ -66,4 +66,4 @@ static_assertions = "1.1"
 # CI test failures.
 trybuild = "=1.0.80"
 # In tests, unlike in production, zerocopy-derive is not optional
-zerocopy-derive = { version = "=0.7.4", path = "zerocopy-derive" }
+zerocopy-derive = { version = "=0.7.5", path = "zerocopy-derive" }

README.md

@@ -8,15 +8,18 @@ made in the doc comment on `src/lib.rs` or in `generate-readme.sh`.
 
 # zerocopy
 
-*Want to help improve zerocopy? Fill out our [user survey][user-survey]!*
+*<span style="font-size: 100%; color:grey;">Want to help improve zerocopy?
+Fill out our [user survey][user-survey]!</span>*
 
-Utilities for safe zero-copy parsing and serialization.
+***<span style="font-size: 140%">Fast, safe, <span
+style="color:red;">compile error</span>. Pick two.</span>***
 
-This crate provides utilities which make it easy to perform zero-copy
-parsing and serialization by allowing zero-copy conversion to/from byte
-slices.
+Zerocopy makes zero-cost memory manipulation effortless. We write `unsafe`
+so you don't have to.
 
-This is enabled by four core marker traits, each of which can be derived
+## Overview
+
+Zerocopy provides four core marker traits, each of which can be derived
 (e.g., `#[derive(FromZeroes)]`):
 - `FromZeroes` indicates that a sequence of zero bytes represents a valid
   instance of a type
@@ -29,8 +32,9 @@ This is enabled by four core marker traits, each of which can be derived
 Types which implement a subset of these traits can then be converted to/from
 byte sequences with little to no runtime overhead.
 
-Note that these traits are ignorant of byte order. For byte order-aware
-types, see the `byteorder` module.
+Zerocopy also provides byte-order aware integer types that support these
+conversions; see the `byteorder` module. These types are especially useful
+for network parsing.
 
 [user-survey]: https://docs.google.com/forms/d/e/1FAIpQLSdzBNTN9tzwsmtyZxRFNL02K36IWCdHWW2ZBckyQS2xiO3i8Q/viewform?usp=published_options
 

src/lib.rs

@@ -7,15 +7,18 @@
 //
 //   ./generate-readme.sh > README.md
 
-//! *Want to help improve zerocopy? Fill out our [user survey][user-survey]!*
+//! *<span style="font-size: 100%; color:grey;">Want to help improve zerocopy?
+//! Fill out our [user survey][user-survey]!</span>*
 //!
-//! Utilities for safe zero-copy parsing and serialization.
+//! ***<span style="font-size: 140%">Fast, safe, <span
+//! style="color:red;">compile error</span>. Pick two.</span>***
 //!
-//! This crate provides utilities which make it easy to perform zero-copy
-//! parsing and serialization by allowing zero-copy conversion to/from byte
-//! slices.
+//! Zerocopy makes zero-cost memory manipulation effortless. We write `unsafe`
+//! so you don't have to.
 //!
-//! This is enabled by four core marker traits, each of which can be derived
+//! # Overview
+//!
+//! Zerocopy provides four core marker traits, each of which can be derived
 //! (e.g., `#[derive(FromZeroes)]`):
 //! - [`FromZeroes`] indicates that a sequence of zero bytes represents a valid
 //!   instance of a type
@@ -28,8 +31,9 @@
 //! Types which implement a subset of these traits can then be converted to/from
 //! byte sequences with little to no runtime overhead.
 //!
-//! Note that these traits are ignorant of byte order. For byte order-aware
-//! types, see the [`byteorder`] module.
+//! Zerocopy also provides byte-order aware integer types that support these
+//! conversions; see the `byteorder` module. These types are especially useful
+//! for network parsing.
 //!
 //! [user-survey]: https://docs.google.com/forms/d/e/1FAIpQLSdzBNTN9tzwsmtyZxRFNL02K36IWCdHWW2ZBckyQS2xiO3i8Q/viewform?usp=published_options
 //!

zerocopy-derive/Cargo.toml

@@ -5,7 +5,7 @@
 [package]
 edition = "2021"
 name = "zerocopy-derive"
-version = "0.7.4"
+version = "0.7.5"
 authors = ["Joshua Liebow-Feeser <[email protected]>"]
 description = "Custom derive for traits from the zerocopy crate"
 license = "BSD-2-Clause"