From 2069c721a94405eeb2da31d89977dc267f8818d8 Mon Sep 17 00:00:00 2001
From: Ed Page <eopage@gmail.com>
Date: Mon, 23 Jan 2023 12:28:06 -0600
Subject: [PATCH] docs(toml): Help people serialize/deserialize values

---
 crates/toml/src/de.rs  | 30 ++++++++++++++++++++++++++++-
 crates/toml/src/ser.rs | 43 +++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 71 insertions(+), 2 deletions(-)

diff --git a/crates/toml/src/de.rs b/crates/toml/src/de.rs
index d4be4b73..36453754 100644
--- a/crates/toml/src/de.rs
+++ b/crates/toml/src/de.rs
@@ -9,6 +9,8 @@
 /// This function will attempt to interpret `s` as a TOML document and
 /// deserialize `T` from the document.
 ///
+/// To deserializes TOML values, instead of documents, see [`ValueDeserializer`].
+///
 /// # Examples
 ///
 /// ```
@@ -98,6 +100,8 @@ impl std::fmt::Display for Error {
 impl std::error::Error for Error {}
 
 /// Deserialization TOML document
+///
+/// To deserializes TOML values, instead of documents, see [`ValueDeserializer`].
 #[cfg(feature = "parse")]
 pub struct Deserializer<'a> {
     input: &'a str,
@@ -200,7 +204,31 @@ impl<'de, 'a> serde::Deserializer<'de> for Deserializer<'a> {
     }
 }
 
-/// Deserialization TOML value
+/// Deserialization TOML [value][crate::Value]
+///
+/// # Example
+///
+/// ```
+/// use serde::Deserialize;
+///
+/// #[derive(Deserialize)]
+/// struct Config {
+///     title: String,
+///     owner: Owner,
+/// }
+///
+/// #[derive(Deserialize)]
+/// struct Owner {
+///     name: String,
+/// }
+///
+/// let config = Config::deserialize(toml::de::ValueDeserializer::new(
+///     r#"{ title = 'TOML Example', owner = { name = 'Lisa' } }"#
+/// )).unwrap();
+///
+/// assert_eq!(config.title, "TOML Example");
+/// assert_eq!(config.owner.name, "Lisa");
+/// ```
 #[cfg(feature = "parse")]
 pub struct ValueDeserializer<'a> {
     input: &'a str,
diff --git a/crates/toml/src/ser.rs b/crates/toml/src/ser.rs
index e4f39be1..b8cf4b1d 100644
--- a/crates/toml/src/ser.rs
+++ b/crates/toml/src/ser.rs
@@ -10,6 +10,8 @@
 /// fail, if `T` contains a map with non-string keys, or if `T` attempts to
 /// serialize an unsupported datatype such as an enum, tuple, or tuple struct.
 ///
+/// To serialize TOML values, instead of documents, see [`ValueSerializer`].
+///
 /// # Examples
 ///
 /// ```
@@ -55,6 +57,8 @@ where
 ///
 /// This is identical to `to_string` except the output string has a more
 /// "pretty" output. See `Serializer::pretty` for more details.
+///
+/// To serialize TOML values, instead of documents, see [`ValueSerializer`].
 #[cfg(feature = "display")]
 pub fn to_string_pretty<T: ?Sized>(value: &T) -> Result<String, Error>
 where
@@ -129,6 +133,8 @@ impl std::error::Error for Error {}
 ///
 /// Currently a serializer always writes its output to an in-memory `String`,
 /// which is passed in when creating the serializer itself.
+///
+/// To serialize TOML values, instead of documents, see [`ValueSerializer`].
 #[non_exhaustive]
 #[cfg(feature = "display")]
 pub struct Serializer<'d> {
@@ -472,7 +478,7 @@ impl<'d> serde::ser::Serializer for Serializer<'d> {
     }
 }
 
-/// Serialization for TOML values.
+/// Serialization for TOML [values][crate::Value].
 ///
 /// This structure implements serialization support for TOML to serialize an
 /// arbitrary type to TOML. Note that the TOML format does not support all
@@ -481,6 +487,41 @@ impl<'d> serde::ser::Serializer for Serializer<'d> {
 ///
 /// Currently a serializer always writes its output to an in-memory `String`,
 /// which is passed in when creating the serializer itself.
+///
+/// # Examples
+///
+/// ```
+/// use serde::Serialize;
+///
+/// #[derive(Serialize)]
+/// struct Config {
+///     database: Database,
+/// }
+///
+/// #[derive(Serialize)]
+/// struct Database {
+///     ip: String,
+///     port: Vec<u16>,
+///     connection_max: u32,
+///     enabled: bool,
+/// }
+///
+/// let config = Config {
+///     database: Database {
+///         ip: "192.168.1.1".to_string(),
+///         port: vec![8001, 8002, 8003],
+///         connection_max: 5000,
+///         enabled: false,
+///     },
+/// };
+///
+/// let mut value = String::new();
+/// serde::Serialize::serialize(
+///     &config,
+///     toml::ser::ValueSerializer::new(&mut value)
+/// ).unwrap();
+/// println!("{}", value)
+/// ```
 #[non_exhaustive]
 #[cfg(feature = "display")]
 pub struct ValueSerializer<'d> {