From 5b91abf52c3be34bd2831233b0a31815f030b1a4 Mon Sep 17 00:00:00 2001
From: David Tolnay <dtolnay@gmail.com>
Date: Mon, 1 Feb 2021 20:47:37 -0800
Subject: [PATCH] Add multi-doc examples

---
 Cargo.toml |  1 +
 src/de.rs  | 37 +++++++++++++++++++++++++++++++++++++
 src/ser.rs | 23 +++++++++++++++++++++++
 3 files changed, 61 insertions(+)

diff --git a/Cargo.toml b/Cargo.toml
index 5bf01525..451b3c01 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -17,6 +17,7 @@ serde = "1.0.69"
 yaml-rust = "0.4.5"
 
 [dev-dependencies]
+anyhow = "1.0"
 indoc = "1.0"
 serde_derive = "1.0"
 
diff --git a/src/de.rs b/src/de.rs
index ff06de05..c959938f 100644
--- a/src/de.rs
+++ b/src/de.rs
@@ -18,6 +18,43 @@ use yaml_rust::parser::{Event as YamlEvent, MarkedEventReceiver, Parser};
 use yaml_rust::scanner::{Marker, TScalarStyle, TokenType};
 
 /// A structure that deserializes YAML into Rust values.
+///
+/// # Examples
+///
+/// Deserializing a single document:
+///
+/// ```
+/// use anyhow::Result;
+/// use serde::Deserialize;
+/// use serde_yaml::Value;
+///
+/// fn main() -> Result<()> {
+///     let input = "---\nk: 107\n";
+///     let de = serde_yaml::Deserializer::from_str(input);
+///     let value = Value::deserialize(de)?;
+///     println!("{:?}", value);
+///     Ok(())
+/// }
+/// ```
+///
+/// Deserializing multi-doc YAML:
+///
+/// ```
+/// use anyhow::Result;
+/// use serde::Deserialize;
+/// use serde_yaml::Value;
+///
+/// fn main() -> Result<()> {
+///     let input = "---\nk: 107\n...\n---\nj: 106\n";
+///
+///     for document in serde_yaml::Deserializer::from_str(input) {
+///         let value = Value::deserialize(document)?;
+///         println!("{:?}", value);
+///     }
+///
+///     Ok(())
+/// }
+/// ```
 pub struct Deserializer<'a> {
     input: Input<'a>,
 }
diff --git a/src/ser.rs b/src/ser.rs
index e19f203e..bdcad44a 100644
--- a/src/ser.rs
+++ b/src/ser.rs
@@ -8,6 +8,29 @@ use std::{fmt, io, num, str};
 use yaml_rust::{yaml, Yaml, YamlEmitter};
 
 /// A structure for serializing Rust values into YAML.
+///
+/// # Example
+///
+/// ```
+/// use anyhow::Result;
+/// use serde::Serialize;
+/// use std::collections::BTreeMap;
+///
+/// fn main() -> Result<()> {
+///     let mut buffer = Vec::new();
+///     let mut ser = serde_yaml::Serializer::new(&mut buffer);
+///
+///     let mut object = BTreeMap::new();
+///     object.insert("k", 107);
+///     object.serialize(&mut ser)?;
+///
+///     object.insert("j", 106);
+///     object.serialize(&mut ser)?;
+///
+///     assert_eq!(buffer, b"---\nk: 107\n...\n---\nj: 106\nk: 107\n");
+///     Ok(())
+/// }
+/// ```
 pub struct Serializer<W> {
     documents: usize,
     writer: W,