From 5558fa46239742720d84c46edb0544732adf4db8 Mon Sep 17 00:00:00 2001
From: Jack O'Connor <oconnor663@gmail.com>
Date: Sun, 21 Jan 2024 20:09:53 -0800
Subject: [PATCH] add a guts docs example

---
 rust/guts/src/lib.rs | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/rust/guts/src/lib.rs b/rust/guts/src/lib.rs
index 3760fa8f2..e9b4914ba 100644
--- a/rust/guts/src/lib.rs
+++ b/rust/guts/src/lib.rs
@@ -1,3 +1,44 @@
+//! # The BLAKE3 Guts API
+//!
+//! See `readme.md`.
+//!
+//! The main entrypoint into this crate is [`DETECTED_IMPL`], which is a global [`Implementation`]
+//! that atomically initializes itself the first time you use it.
+//!
+//! # Example
+//!
+//! ```rust
+//! use blake3_guts::{TransposedVectors, DETECTED_IMPL, IV_BYTES, PARENT, ROOT};
+//!
+//! // Hash an input of exactly two chunks.
+//! let input = [0u8; 2048];
+//! let mut outputs = TransposedVectors::new();
+//! let (left_outputs, _) = DETECTED_IMPL.split_transposed_vectors(&mut outputs);
+//! DETECTED_IMPL.hash_chunks(
+//!     &input,
+//!     &IV_BYTES,
+//!     0, // counter
+//!     0, // flags
+//!     left_outputs,
+//! );
+//! let root_node = outputs.extract_parent_node(0);
+//! let hash = DETECTED_IMPL.compress(
+//!     &root_node,
+//!     64, // block_len
+//!     &IV_BYTES,
+//!     0, // counter
+//!     PARENT | ROOT,
+//! );
+//!
+//! // Compute the same hash using the reference implementation.
+//! let mut reference_hasher = reference_impl::Hasher::new();
+//! reference_hasher.update(&input);
+//! let mut expected_hash = [0u8; 32];
+//! reference_hasher.finalize(&mut expected_hash);
+//!
+//! assert_eq!(hash, expected_hash);
+//! ```
+
 // Tests always require libstd.
 #![cfg_attr(all(not(feature = "std"), not(test)), no_std)]