From 6f945c4c67af1fd388674177f4b2418d2c849eab Mon Sep 17 00:00:00 2001
From: Mathieu Baudet <1105398+ma2bd@users.noreply.github.com>
Date: Thu, 6 Jun 2024 10:37:47 +0200
Subject: [PATCH] add documentation

---
 serde-reflection/README.md      | 7 +++++++
 serde-reflection/src/lib.rs     | 7 +++++++
 serde-reflection/tests/serde.rs | 4 ++++
 3 files changed, 18 insertions(+)

diff --git a/serde-reflection/README.md b/serde-reflection/README.md
index 21e737285..ac15c588b 100644
--- a/serde-reflection/README.md
+++ b/serde-reflection/README.md
@@ -105,6 +105,13 @@ use the crate [`serde-name`](https://crates.io/crates/serde-name) and its adapte
 terminate. (Work around: re-order the variants. For instance `enum List {
 Some(Box<List>), None}` must be rewritten `enum List { None, Some(Box<List>)}`.)
 
+* Certain standard types such as `std::num::NonZeroU8` may not be tracked as a
+container and appear simply as their underlying primitive type (e.g. `u8`) in the
+formats. This loss of information makes it difficult to use `trace_value` to work
+around deserialization invariants (see example below). As a work around, you may
+override the default for the primitive type using `TracerConfig` (e.g. `let config =
+TracerConfig::default().default_u8_value(1);`).
+
 ### Security CAVEAT
 
 At this time, `HashSet<T>` and `BTreeSet<T>` are treated as sequences (i.e. vectors)
diff --git a/serde-reflection/src/lib.rs b/serde-reflection/src/lib.rs
index 861796ea1..9fc0895f0 100644
--- a/serde-reflection/src/lib.rs
+++ b/serde-reflection/src/lib.rs
@@ -108,6 +108,13 @@
 //! terminate. (Work around: re-order the variants. For instance `enum List {
 //! Some(Box<List>), None}` must be rewritten `enum List { None, Some(Box<List>)}`.)
 //!
+//! * Certain standard types such as `std::num::NonZeroU8` may not be tracked as a
+//! container and appear simply as their underlying primitive type (e.g. `u8`) in the
+//! formats. This loss of information makes it difficult to use `trace_value` to work
+//! around deserialization invariants (see example below). As a work around, you may
+//! override the default for the primitive type using `TracerConfig` (e.g. `let config =
+//! TracerConfig::default().default_u8_value(1);`).
+//!
 //! ## Security CAVEAT
 //!
 //! At this time, `HashSet<T>` and `BTreeSet<T>` are treated as sequences (i.e. vectors)
diff --git a/serde-reflection/tests/serde.rs b/serde-reflection/tests/serde.rs
index 9a2514e3f..040786bc7 100644
--- a/serde-reflection/tests/serde.rs
+++ b/serde-reflection/tests/serde.rs
@@ -476,6 +476,10 @@ fn test_default_value_for_primitive_types() {
     let mut tracer = Tracer::new(config);
     let samples = Samples::new();
 
+    let (format, value) = tracer.trace_type_once::<std::num::NonZeroU8>(&samples).unwrap();
+    assert_eq!(format, Format::U8); // Not a container
+    assert_eq!(value.get(), 1);
+
     let (format, value) = tracer.trace_type_once::<u8>(&samples).unwrap();
     assert_eq!(format, Format::U8);
     assert_eq!(value, 1);