Introduce 'Code Generation' documentation

.github/workflows/docs.yml

@@ -90,7 +90,7 @@ jobs:
             #
             # TODO(#1228): Use `jq` to parse these from `Cargo.toml` instead of
             # hard-coding them once we've gotten it working again.
-            METADATA_DOCS_RS_RUSTDOC_ARGS='--cfg doc_cfg --generate-link-to-definition'
+            METADATA_DOCS_RS_RUSTDOC_ARGS='--cfg doc_cfg --generate-link-to-definition --extend-css rustdoc/style.css'
             export RUSTDOCFLAGS="-Z unstable-options --document-hidden-items $METADATA_DOCS_RS_RUSTDOC_ARGS"
 
             # TODO: Use `./cargo.sh` instead once we've debugged why it won't work.

Cargo.toml

@@ -89,7 +89,7 @@ pinned-nightly = "nightly-2026-01-25"
 
 [package.metadata.docs.rs]
 all-features = true
-rustdoc-args = ["--cfg", "doc_cfg", "--generate-link-to-definition"]
+rustdoc-args = ["--cfg", "doc_cfg", "--generate-link-to-definition", "--extend-css", "rustdoc/style.css"]
 
 [package.metadata.playground]
 features = ["__internal_use_only_features_that_work_on_stable"]

benches/formats/coco.rs

@@ -1,24 +1,3 @@
-// Copyright 2026 The Fuchsia Authors
-//
-// Licensed under a BSD-style license <LICENSE-BSD>, Apache License, Version 2.0
-// <LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0>, or the MIT
-// license <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option.
-// This file may not be copied, modified, or distributed except according to
-// those terms.
-
-//! This modules defines two formats similar to the one used to illustrate the
-//! examples of [`zerocopy::TryFromBytes`]. The basic structure of these formats
-//! is a [`Packet`], which has a parameterizable leading field, followed by
-//! two-fixed byte fields, followed by a dynamically sized field. This format is
-//! consumed by our benchmarks either as a [`CocoPacket`] (which begins with the
-//! leading bytes `0xC0C0`), or a [`LocoPacket`] (which begins two bytes of any
-//! value). Both formats share the following qualities which stress-test our
-//! benchmarks:
-//!
-//! - They have a minimum alignment of two.
-//! - They have a minimum size of four bytes.
-//! - They have an even size.
-
 use zerocopy_derive::*;
 
 // The only valid value of this type are the bytes `0xC0C0`.

benches/ref_from_bytes.rs

@@ -1,17 +1,7 @@
-// Copyright 2026 The Fuchsia Authors
-//
-// Licensed under a BSD-style license <LICENSE-BSD>, Apache License, Version 2.0
-// <LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0>, or the MIT
-// license <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option.
-// This file may not be copied, modified, or distributed except according to
-// those terms.
-
-use zerocopy::FromBytes;
-
 #[path = "formats/coco.rs"]
 mod format;
 
 #[unsafe(no_mangle)]
 fn codegen_test(source: &[u8]) -> Option<&format::LocoPacket> {
-    FromBytes::ref_from_bytes(source).ok()
+    zerocopy::FromBytes::ref_from_bytes(source).ok()
 }

benches/ref_from_bytes_with_elems.rs

@@ -1,17 +1,7 @@
-// Copyright 2026 The Fuchsia Authors
-//
-// Licensed under a BSD-style license <LICENSE-BSD>, Apache License, Version 2.0
-// <LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0>, or the MIT
-// license <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option.
-// This file may not be copied, modified, or distributed except according to
-// those terms.
-
-use zerocopy::FromBytes;
-
 #[path = "formats/coco.rs"]
 mod format;
 
 #[unsafe(no_mangle)]
 fn codegen_test(source: &[u8], count: usize) -> Option<&format::LocoPacket> {
-    FromBytes::ref_from_bytes_with_elems(source, count).ok()
+    zerocopy::FromBytes::ref_from_bytes_with_elems(source, count).ok()
 }

benches/ref_from_prefix.rs

@@ -1,19 +1,9 @@
-// Copyright 2026 The Fuchsia Authors
-//
-// Licensed under a BSD-style license <LICENSE-BSD>, Apache License, Version 2.0
-// <LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0>, or the MIT
-// license <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option.
-// This file may not be copied, modified, or distributed except according to
-// those terms.
-
-use zerocopy::FromBytes;
-
 #[path = "formats/coco.rs"]
 mod format;
 
 #[unsafe(no_mangle)]
 fn codegen_test(source: &[u8]) -> Option<&format::LocoPacket> {
-    match FromBytes::ref_from_prefix(source) {
+    match zerocopy::FromBytes::ref_from_prefix(source) {
         Ok((packet, _rest)) => Some(packet),
         _ => None,
     }

benches/ref_from_prefix_with_elems.rs

@@ -1,19 +1,9 @@
-// Copyright 2026 The Fuchsia Authors
-//
-// Licensed under a BSD-style license <LICENSE-BSD>, Apache License, Version 2.0
-// <LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0>, or the MIT
-// license <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option.
-// This file may not be copied, modified, or distributed except according to
-// those terms.
-
-use zerocopy::FromBytes;
-
 #[path = "formats/coco.rs"]
 mod format;
 
 #[unsafe(no_mangle)]
 fn codegen_test(source: &[u8], count: usize) -> Option<&format::LocoPacket> {
-    match FromBytes::ref_from_prefix_with_elems(source, count) {
+    match zerocopy::FromBytes::ref_from_prefix_with_elems(source, count) {
         Ok((packet, _rest)) => Some(packet),
         _ => None,
     }

benches/ref_from_suffix.rs

@@ -1,19 +1,9 @@
-// Copyright 2026 The Fuchsia Authors
-//
-// Licensed under a BSD-style license <LICENSE-BSD>, Apache License, Version 2.0
-// <LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0>, or the MIT
-// license <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option.
-// This file may not be copied, modified, or distributed except according to
-// those terms.
-
-use zerocopy::FromBytes;
-
 #[path = "formats/coco.rs"]
 mod format;
 
 #[unsafe(no_mangle)]
 fn codegen_test(source: &[u8]) -> Option<&format::LocoPacket> {
-    match FromBytes::ref_from_suffix(source) {
+    match zerocopy::FromBytes::ref_from_suffix(source) {
         Ok((_rest, packet)) => Some(packet),
         _ => None,
     }

benches/ref_from_suffix_with_elems.rs

@@ -1,19 +1,9 @@
-// Copyright 2026 The Fuchsia Authors
-//
-// Licensed under a BSD-style license <LICENSE-BSD>, Apache License, Version 2.0
-// <LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0>, or the MIT
-// license <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option.
-// This file may not be copied, modified, or distributed except according to
-// those terms.
-
-use zerocopy::FromBytes;
-
 #[path = "formats/coco.rs"]
 mod format;
 
 #[unsafe(no_mangle)]
 fn codegen_test(source: &[u8], count: usize) -> Option<&format::LocoPacket> {
-    match FromBytes::ref_from_suffix_with_elems(source, count) {
+    match zerocopy::FromBytes::ref_from_suffix_with_elems(source, count) {
         Ok((_rest, packet)) => Some(packet),
         _ => None,
     }

benches/transmute_ref.rs

@@ -1,12 +1,3 @@
-// Copyright 2026 The Fuchsia Authors
-//
-// Licensed under a BSD-style license <LICENSE-BSD>, Apache License, Version 2.0
-// <LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0>, or the MIT
-// license <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option.
-// This file may not be copied, modified, or distributed except according to
-// those terms.
-
-use zerocopy::transmute_ref;
 use zerocopy_derive::*;
 
 #[path = "formats/coco.rs"]
@@ -21,5 +12,5 @@ struct MinimalViableSource {
 
 #[unsafe(no_mangle)]
 fn codegen_test(source: &MinimalViableSource) -> &format::LocoPacket {
-    transmute_ref!(source)
+    zerocopy::transmute_ref!(source)
 }

benches/try_ref_from_bytes.rs

@@ -1,17 +1,7 @@
-// Copyright 2026 The Fuchsia Authors
-//
-// Licensed under a BSD-style license <LICENSE-BSD>, Apache License, Version 2.0
-// <LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0>, or the MIT
-// license <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option.
-// This file may not be copied, modified, or distributed except according to
-// those terms.
-
-use zerocopy::TryFromBytes;
-
 #[path = "formats/coco.rs"]
 mod format;
 
 #[unsafe(no_mangle)]
 fn codegen_test(source: &[u8]) -> Option<&format::CocoPacket> {
-    TryFromBytes::try_ref_from_bytes(source).ok()
+    zerocopy::TryFromBytes::try_ref_from_bytes(source).ok()
 }

benches/try_ref_from_bytes_with_elems.rs

@@ -1,17 +1,7 @@
-// Copyright 2026 The Fuchsia Authors
-//
-// Licensed under a BSD-style license <LICENSE-BSD>, Apache License, Version 2.0
-// <LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0>, or the MIT
-// license <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option.
-// This file may not be copied, modified, or distributed except according to
-// those terms.
-
-use zerocopy::TryFromBytes;
-
 #[path = "formats/coco.rs"]
 mod format;
 
 #[unsafe(no_mangle)]
 fn codegen_test(source: &[u8], count: usize) -> Option<&format::CocoPacket> {
-    TryFromBytes::try_ref_from_bytes_with_elems(source, count).ok()
+    zerocopy::TryFromBytes::try_ref_from_bytes_with_elems(source, count).ok()
 }

benches/try_ref_from_prefix.rs

@@ -1,19 +1,9 @@
-// Copyright 2026 The Fuchsia Authors
-//
-// Licensed under a BSD-style license <LICENSE-BSD>, Apache License, Version 2.0
-// <LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0>, or the MIT
-// license <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option.
-// This file may not be copied, modified, or distributed except according to
-// those terms.
-
-use zerocopy::TryFromBytes;
-
 #[path = "formats/coco.rs"]
 mod format;
 
 #[unsafe(no_mangle)]
 fn codegen_test(source: &[u8]) -> Option<&format::CocoPacket> {
-    match TryFromBytes::try_ref_from_prefix(source) {
+    match zerocopy::TryFromBytes::try_ref_from_prefix(source) {
         Ok((packet, _rest)) => Some(packet),
         _ => None,
     }

benches/try_ref_from_prefix_with_elems.rs

@@ -1,19 +1,9 @@
-// Copyright 2026 The Fuchsia Authors
-//
-// Licensed under a BSD-style license <LICENSE-BSD>, Apache License, Version 2.0
-// <LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0>, or the MIT
-// license <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option.
-// This file may not be copied, modified, or distributed except according to
-// those terms.
-
-use zerocopy::TryFromBytes;
-
 #[path = "formats/coco.rs"]
 mod format;
 
 #[unsafe(no_mangle)]
 fn codegen_test(source: &[u8], count: usize) -> Option<&format::CocoPacket> {
-    match TryFromBytes::try_ref_from_prefix_with_elems(source, count) {
+    match zerocopy::TryFromBytes::try_ref_from_prefix_with_elems(source, count) {
         Ok((packet, _rest)) => Some(packet),
         _ => None,
     }

benches/try_ref_from_suffix.rs

@@ -1,19 +1,9 @@
-// Copyright 2026 The Fuchsia Authors
-//
-// Licensed under a BSD-style license <LICENSE-BSD>, Apache License, Version 2.0
-// <LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0>, or the MIT
-// license <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option.
-// This file may not be copied, modified, or distributed except according to
-// those terms.
-
-use zerocopy::TryFromBytes;
-
 #[path = "formats/coco.rs"]
 mod format;
 
 #[unsafe(no_mangle)]
 fn codegen_test(source: &[u8]) -> Option<&format::CocoPacket> {
-    match TryFromBytes::try_ref_from_suffix(source) {
+    match zerocopy::TryFromBytes::try_ref_from_suffix(source) {
         Ok((_rest, packet)) => Some(packet),
         _ => None,
     }

benches/try_ref_from_suffix_with_elems.rs

@@ -1,19 +1,9 @@
-// Copyright 2026 The Fuchsia Authors
-//
-// Licensed under a BSD-style license <LICENSE-BSD>, Apache License, Version 2.0
-// <LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0>, or the MIT
-// license <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option.
-// This file may not be copied, modified, or distributed except according to
-// those terms.
-
-use zerocopy::TryFromBytes;
-
 #[path = "formats/coco.rs"]
 mod format;
 
 #[unsafe(no_mangle)]
 fn codegen_test(source: &[u8], count: usize) -> Option<&format::CocoPacket> {
-    match TryFromBytes::try_ref_from_suffix_with_elems(source, count) {
+    match zerocopy::TryFromBytes::try_ref_from_suffix_with_elems(source, count) {
         Ok((_rest, packet)) => Some(packet),
         _ => None,
     }

benches/try_transmute_ref.rs

@@ -1,12 +1,3 @@
-// Copyright 2026 The Fuchsia Authors
-//
-// Licensed under a BSD-style license <LICENSE-BSD>, Apache License, Version 2.0
-// <LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0>, or the MIT
-// license <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option.
-// This file may not be copied, modified, or distributed except according to
-// those terms.
-
-use zerocopy::try_transmute_ref;
 use zerocopy_derive::*;
 
 #[path = "formats/coco.rs"]
@@ -21,5 +12,5 @@ struct MinimalViableSource {
 
 #[unsafe(no_mangle)]
 fn codegen_test(source: &MinimalViableSource) -> Option<&format::CocoPacket> {
-    try_transmute_ref!(source).ok()
+    zerocopy::try_transmute_ref!(source).ok()
 }

rustdoc/style.css

@@ -0,0 +1,53 @@
+/*
+Copyright 2026 The Fuchsia Authors
+
+Licensed under a BSD-style license <LICENSE-BSD>, Apache License, Version 2.0
+<LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0>, or the MIT
+license <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option.
+This file may not be copied, modified, or distributed except according to
+those terms.
+*/
+
+.codegen-tabs {
+    display: grid;
+    grid-template-columns: repeat(3, minmax(200px, 1fr));
+    grid-template-rows: auto 1fr;
+    column-gap: 1rem;
+}
+
+.codegen-tabs:not(:has(details[open]))::after {
+    grid-column: 1/-1;
+    content: 'Click one of the above headers to expand its contents.';
+    font-style: italic;
+}
+
+.codegen-tabs details {
+    display: grid;
+    grid-column: 1 / -1;
+    grid-row: 1 / span 2;
+    grid-template-columns: subgrid;
+    grid-template-rows: subgrid;
+}
+
+.codegen-tabs summary {
+    display: grid;
+    grid-column: var(--n) / span 1;
+    grid-row: 1;
+    z-index: 1;
+    border-bottom: 2px solid var(--headings-border-bottom-color);
+    cursor: pointer;
+}
+
+.codegen-tabs details[open] :is(summary) {
+    background-color: var(--code-block-background-color);
+    border-bottom-color: var(--target-border-color);
+}
+
+.codegen-tabs details::details-content {
+    grid-column: 1 / -1;
+    grid-row: 2;
+}
+
+.codegen-tabs details:not([open])::details-content {
+    display: none;
+}