Add documentation

Author: Jan Jansen

src/de/mod.rs

@@ -15,17 +15,49 @@ mod map;
 mod seq;
 mod var;
 
-pub struct Deserializer<R: Read> {
-    depth: usize,
-    reader: EventReader<R>,
-    peeked: Option<XmlEvent>,
-    is_map_value: bool,
-}
-
+/// A convenience method for deserialize some object from a string.
+///
+/// ```rust
+/// # #[macro_use]
+/// # extern crate serde_derive;
+/// # extern crate serde;
+/// # extern crate serde_xml_rs;
+/// # use serde_xml_rs::from_str;
+/// #[derive(Debug, Deserialize, PartialEq)]
+/// struct Item {
+///     name: String,
+///     source: String,
+/// }
+/// # fn main() {
+/// let s = r##"<item name="hello" source="world.rs" />"##;
+/// let item: Item = from_str(s).unwrap();
+/// assert_eq!(item, Item { name: "hello".to_string(),source: "world.rs".to_string()});
+/// # }
+/// ```
 pub fn from_str<'de, T: de::Deserialize<'de>>(s: &str) -> Result<T> {
-    deserialize(s.as_bytes())
+    from_reader(s.as_bytes())
 }
 
+
+/// A convenience method for deserialize some object from a reader.
+///
+/// ```rust
+/// # #[macro_use]
+/// # extern crate serde_derive;
+/// # extern crate serde;
+/// # extern crate serde_xml_rs;
+/// # use serde_xml_rs::from_reader;
+/// #[derive(Debug, Deserialize, PartialEq)]
+/// struct Item {
+///     name: String,
+///     source: String,
+/// }
+/// # fn main() {
+/// let s = r##"<item name="hello" source="world.rs" />"##;
+/// let item: Item = from_reader(s.as_bytes()).unwrap();
+/// assert_eq!(item, Item { name: "hello".to_string(),source: "world.rs".to_string()});
+/// # }
+/// ```
 pub fn from_reader<'de, R: Read, T: Deserialize<'de>>(reader: R) -> Result<T> {
     T::deserialize(&mut Deserializer::new_from_reader(reader))
 }
@@ -34,6 +66,13 @@ pub fn deserialize<'de, R: Read, T: Deserialize<'de>>(reader: R) -> Result<T> {
     from_reader(reader)
 }
 
+pub struct Deserializer<R: Read> {
+    depth: usize,
+    reader: EventReader<R>,
+    peeked: Option<XmlEvent>,
+    is_map_value: bool,
+}
+
 impl<'de, R: Read> Deserializer<R> {
     pub fn new(reader: EventReader<R>) -> Self {
         Deserializer {

src/lib.rs

@@ -1,3 +1,35 @@
+//!
+//! ```rust
+//! extern crate serde;
+//! extern crate serde_xml_rs;
+//!
+//! #[macro_use]
+//! extern crate serde_derive;
+//!
+//! use serde_xml_rs::{from_str, to_string};
+//!
+//! #[derive(Debug, Serialize, Deserialize, PartialEq)]
+//! struct Item {
+//!     name: String,
+//!     source: String,
+//! }
+//!
+//! fn main() {
+//!     let src = r#"<Item><name>Banana</name><source>Store</source></Item>"#;
+//!     let should_be = Item {
+//!         name: "Banana".to_string(),
+//!         source: "Store".to_string(),
+//!     };
+//!
+//!     let item: Item = from_str(src).unwrap();
+//!     assert_eq!(item, should_be);
+//!
+//!     let reserialized_item = to_string(&item).unwrap();
+//!     assert_eq!(src, reserialized_item);
+//! }
+//! ```
+
+
 #[macro_use]
 extern crate error_chain;
 #[macro_use]

src/ser/mod.rs

@@ -44,11 +44,70 @@ pub fn serialize<W: Write, S: Serialize>(value: S, writer: W) -> Result<()> {
     to_writer(writer, &value)
 }
 
+
+/// A convenience method for serializing some object to a buffer.
+///
+/// You'll almost always want to use this over any of the other things in the
+/// `serde_xml_rs::to_writer` module.
+///
+///
+/// # Examples
+///
+/// ```rust
+/// # #[macro_use]
+/// # extern crate serde_derive;
+/// # extern crate serde;
+/// # extern crate serde_xml_rs;
+/// # use serde_xml_rs::to_writer;
+/// #[derive(Serialize)]
+/// struct Person {
+///   name: String,
+///   age: u32,
+/// }
+///
+/// # fn main() {
+/// let mut buffer = Vec::new();
+/// let joe = Person {name: "Joe".to_string(), age: 42};
+///
+/// to_writer(&mut buffer, &joe).unwrap();
+///
+/// let serialized = String::from_utf8(buffer).unwrap();
+/// println!("{}", serialized);
+/// # }
+/// ```
 pub fn to_writer<W: Write, S: Serialize>(writer: W, value: &S) -> Result<()> {
     let mut ser = Serializer::new(writer);
     value.serialize(&mut ser)
 }
 
+
+/// A convenience method for serializing some object to a string.
+///
+/// You'll almost always want to use this over any of the other things in the
+/// `serde_xml_rs::to_string` module.
+///
+///
+/// # Examples
+///
+/// ```rust
+/// # #[macro_use]
+/// # extern crate serde_derive;
+/// # extern crate serde;
+/// # extern crate serde_xml_rs;
+/// # use serde_xml_rs::to_string;
+/// #[derive(Serialize)]
+/// struct Person {
+///   name: String,
+///   age: u32,
+/// }
+///
+/// # fn main() {
+///
+/// let joe = Person {name: "Joe".to_string(), age: 42};
+/// let serialized = to_string(&joe).unwrap();
+/// println!("{}", serialized);
+/// # }
+/// ```
 pub fn to_string<S: Serialize>(value: &S) -> Result<String> {
     // Create a buffer and serialize our nodes into it
     let mut writer = Vec::with_capacity(128);