From 16d5e67fa5b76782c1c48fe96ed803b39e6d8877 Mon Sep 17 00:00:00 2001
From: Alex Crichton <alex@alexcrichton.com>
Date: Sun, 22 Jun 2014 22:31:09 -0700
Subject: [PATCH] Clean up warnings and documentation

---
 src/serialization.rs | 69 ++++++++++++++++++++++++++++++++------------
 src/toml.rs          |  2 +-
 2 files changed, 51 insertions(+), 20 deletions(-)

diff --git a/src/serialization.rs b/src/serialization.rs
index 515e8dd..ef2ac88 100644
--- a/src/serialization.rs
+++ b/src/serialization.rs
@@ -1,10 +1,8 @@
-#![allow(warnings)]
-
 use std::collections::HashMap;
 use std::mem;
 
 use serialize;
-use {Value, Table, Array, String, Integer, Float, Boolean};
+use {Value, Table, Array, String, Integer, Float, Boolean, Parser};
 
 /// A structure to transform Rust values into TOML values.
 ///
@@ -43,6 +41,11 @@ pub struct Encoder {
     state: EncoderState,
 }
 
+/// A structure to transform TOML values into Rust values.
+///
+/// This decoder implements the serialization `Decoder` interface, allowing
+/// `Decodable` types to be generated by this decoder. The input is any
+/// arbitrary TOML value.
 pub struct Decoder {
     toml: Option<Value>,
 }
@@ -313,7 +316,35 @@ impl serialize::Encoder<Error> for Encoder {
     }
 }
 
+/// Decodes a TOML value into a decodable type.
+///
+/// This function will consume the given TOML value and attempt to decode it
+/// into the type specified. If decoding fails, `None` will be returned. If a
+/// finer-grained error is desired, then it is recommended to use `Decodable`
+/// directly.
+pub fn decode<T: serialize::Decodable<Decoder, Error>>(toml: Value)
+    -> Option<T>
+{
+    serialize::Decodable::decode(&mut Decoder::new(toml)).ok()
+}
+
+/// Decodes a string into a toml-encoded value.
+///
+/// This function will parse the given string into a TOML value, and then parse
+/// the TOML value into the desired type. If any error occurs `None` is return.
+/// If more fine-grained errors are desired, these steps should be driven
+/// manually.
+pub fn decode_str<T: serialize::Decodable<Decoder, Error>>(s: &str)
+    -> Option<T>
+{
+    Parser::new(s).parse().and_then(|t| decode(Table(t)))
+}
+
 impl Decoder {
+    /// Creates a new decoder, consuming the TOML value to decode.
+    ///
+    /// This decoder can be passed to the `Decodable` methods or driven
+    /// manually.
     pub fn new(toml: Value) -> Decoder {
         Decoder { toml: Some(toml) }
     }
@@ -389,34 +420,34 @@ impl serialize::Decoder<Error> for Decoder {
     }
 
     // Compound types:
-    fn read_enum<T>(&mut self, name: &str,
-                    f: |&mut Decoder| -> Result<T, Error>) -> Result<T, Error> {
+    fn read_enum<T>(&mut self, _name: &str,
+                    _f: |&mut Decoder| -> Result<T, Error>) -> Result<T, Error> {
         fail!()
     }
 
     fn read_enum_variant<T>(&mut self,
-                            names: &[&str],
-                            f: |&mut Decoder, uint| -> Result<T, Error>)
+                            _names: &[&str],
+                            _f: |&mut Decoder, uint| -> Result<T, Error>)
                             -> Result<T, Error> {
         fail!()
     }
     fn read_enum_variant_arg<T>(&mut self,
-                                a_idx: uint,
-                                f: |&mut Decoder| -> Result<T, Error>)
+                                _a_idx: uint,
+                                _f: |&mut Decoder| -> Result<T, Error>)
                                 -> Result<T, Error> {
         fail!()
     }
 
     fn read_enum_struct_variant<T>(&mut self,
-                                   names: &[&str],
-                                   f: |&mut Decoder, uint| -> Result<T, Error>)
+                                   _names: &[&str],
+                                   _f: |&mut Decoder, uint| -> Result<T, Error>)
                                    -> Result<T, Error> {
         fail!()
     }
     fn read_enum_struct_variant_field<T>(&mut self,
-                                         f_name: &str,
-                                         f_idx: uint,
-                                         f: |&mut Decoder| -> Result<T, Error>)
+                                         _f_name: &str,
+                                         _f_idx: uint,
+                                         _f: |&mut Decoder| -> Result<T, Error>)
                                          -> Result<T, Error> {
         fail!()
     }
@@ -432,7 +463,7 @@ impl serialize::Decoder<Error> for Decoder {
     }
     fn read_struct_field<T>(&mut self,
                             f_name: &str,
-                            f_idx: uint,
+                            _f_idx: uint,
                             f: |&mut Decoder| -> Result<T, Error>)
                             -> Result<T, Error> {
         match self.toml {
@@ -460,15 +491,15 @@ impl serialize::Decoder<Error> for Decoder {
     }
 
     fn read_tuple_struct<T>(&mut self,
-                            s_name: &str,
-                            f: |&mut Decoder, uint| -> Result<T, Error>)
+                            _s_name: &str,
+                            _f: |&mut Decoder, uint| -> Result<T, Error>)
         -> Result<T, Error>
     {
         fail!()
     }
     fn read_tuple_struct_arg<T>(&mut self,
-                                a_idx: uint,
-                                f: |&mut Decoder| -> Result<T, Error>)
+                                _a_idx: uint,
+                                _f: |&mut Decoder| -> Result<T, Error>)
         -> Result<T, Error>
     {
         fail!()
diff --git a/src/toml.rs b/src/toml.rs
index 7c75085..33be0f8 100644
--- a/src/toml.rs
+++ b/src/toml.rs
@@ -47,7 +47,7 @@ use std::from_str::FromStr;
 
 pub use parser::{Parser, Error};
 pub use serialization::{Encoder, encode, encode_str};
-// pub use serialization::{Encoder, encode, encode_str};
+pub use serialization::{Decoder, decode, decode_str};
 pub use serialization::{Error, NeedsKey, NoValue};
 pub use serialization::{InvalidMapKeyLocation, InvalidMapKeyType};