Merge pull request #190 from dtolnay/doc

Add multi-doc examples

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"
 

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>,
 }

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", 74);
+///     object.serialize(&mut ser)?;
+///
+///     assert_eq!(buffer, b"---\nk: 107\n...\n---\nJ: 74\nk: 107\n");
+///     Ok(())
+/// }
+/// ```
 pub struct Serializer<W> {
     documents: usize,
     writer: W,