From e4c95cf2a3d74080c6b529faf195f4e32c57f9bb Mon Sep 17 00:00:00 2001
From: Timothy Warren <twarren@nabancard.com>
Date: Thu, 20 Feb 2020 15:30:06 -0500
Subject: [PATCH] Improve docs

---
 src/lib.rs | 85 +++++++++++++++++++++++++++++++++++++-----------------
 1 file changed, 59 insertions(+), 26 deletions(-)

diff --git a/src/lib.rs b/src/lib.rs
index 41d5f03..13eedcd 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -75,8 +75,9 @@ pub enum JSONValue {
 impl JSONValue {
     /// Convert the wrapped `JSONValue` to its simpler rust value
     ///
-    /// This is a convenience method that calls the `from` method
-    /// for the appropriate type.
+    /// This is a convenience method that calls the `try_from` method
+    /// for the appropriate type. This will panic if the output type of
+    /// the unwrap does not match the type of value in the `JSONValue` struct.
     ///
     /// Example:
     /// ```
@@ -90,6 +91,18 @@ impl JSONValue {
     ///
     /// # assert_eq!(str, &s);
     /// ```
+    ///
+    /// Panicing example:
+    /// ```should_panic
+    /// # use naive_json_parser::JSONValue;
+    /// // Don't try to unwrap one type as another
+    /// let json = JSONValue::from(4.5);
+    ///
+    /// // json currently has a `JSONValue::Number` value
+    /// // trying to unwrap the value as a string will result in a
+    /// // panic
+    /// let s: String = json.unwrap(); // This panics
+    /// ```
     pub fn unwrap<T: TryFrom<JSONValue>>(self) -> T {
         match T::try_from(self) {
             Ok(val) => val,
@@ -102,6 +115,8 @@ impl TryFrom<JSONValue> for JSONMap {
     type Error = &'static str;
 
     /// Extracts the `HashMap` in the `JSONValue` enum, if it exists.
+    ///
+    /// Returns an error if `v` is not a `JSONValue::Object`.
     fn try_from(v: JSONValue) -> Result<Self, Self::Error> {
         match v {
             JSONValue::Object(o) => Ok(o),
@@ -114,6 +129,8 @@ impl TryFrom<JSONValue> for JSONArray {
     type Error = &'static str;
 
     /// Extracts the `Vec` in the `JSONValue` enum, if it exists.
+    ///
+    /// Returns an error if `v` is not a `JSONValue::Array`.
     fn try_from(v: JSONValue) -> Result<Self, Self::Error> {
         match v {
             JSONValue::Array(a) => Ok(a),
@@ -126,6 +143,8 @@ impl TryFrom<JSONValue> for f64 {
     type Error = &'static str;
 
     /// Extracts the `f64` in the `JSONValue` enum, if it exists.
+    ///
+    /// Returns an error if `v` is not a `JSONValue::Number`.
     fn try_from(v: JSONValue) -> Result<Self, Self::Error> {
         match v {
             JSONValue::Number(n) => Ok(n),
@@ -138,6 +157,8 @@ impl TryFrom<JSONValue> for String {
     type Error = &'static str;
 
     /// Extracts the `String` in the `JSONValue` enum, if it exists.
+    ///
+    /// Returns an error if `v` is not a `JSONValue::String`.
     fn try_from(v: JSONValue) -> Result<Self, Self::Error> {
         match v {
             JSONValue::String(s) => Ok(s),
@@ -150,6 +171,8 @@ impl TryFrom<JSONValue> for bool {
     type Error = &'static str;
 
     /// Extracts the `bool` in the `JSONValue` enum, if it exists.
+    ///
+    /// Returns an error if `v` is not a `JSONValue::True` or `JSONValue::False`.
     fn try_from(v: JSONValue) -> Result<Self, Self::Error> {
         match v {
             JSONValue::True => Ok(true),
@@ -160,26 +183,55 @@ impl TryFrom<JSONValue> for bool {
 }
 
 impl From<JSONValue> for () {
-    /// This will just swallow the enum value and return a unit tuple
+    /// This will just swallow the enum value and return a unit tuple.
+    ///
+    /// This impl only exists to mirror the `()` to `JSONValue::Null`
+    /// conversion.
     fn from(_: JSONValue) -> () {
         ()
     }
 }
 
 impl From<JSONMap> for JSONValue {
-    /// Wraps the `HashMap` in the `JSONValue` enum
+    /// Wraps the `HashMap` in the `JSONValue` enum,
+    /// returning a `JSONValue::Object`
     fn from(val: JSONMap) -> JSONValue {
         Self::Object(val)
     }
 }
 
 impl From<JSONArray> for JSONValue {
-    /// Wraps the `Vec` in the `JSONValue` enum
+    /// Wraps the `Vec` in the `JSONValue` enum,
+    /// returning a `JSONValue::Array`
     fn from(val: JSONArray) -> JSONValue {
         Self::Array(val)
     }
 }
 
+impl From<f64> for JSONValue {
+    /// Wraps the `f64` in the `JSONValue` enum,
+    /// returning a `JSONValue::Number`
+    fn from(n: f64) -> Self {
+        Self::Number(n)
+    }
+}
+
+impl From<String> for JSONValue {
+    /// Wraps the `String` in the `JSONValue` enum,
+    /// returning a `JSONValue::String`
+    fn from(s: String) -> Self {
+        Self::String(s)
+    }
+}
+
+impl From<&str> for JSONValue {
+    /// Creates a `String` and wraps it in the `JSONValue` enum,
+    /// returning a `JSONValue::String`
+    fn from(s: &str) -> Self {
+        Self::String(String::from(s))
+    }
+}
+
 impl From<bool> for JSONValue {
     /// Sets the `JSONValue` enum to the `True` or `False` value
     fn from(val: bool) -> Self {
@@ -190,12 +242,6 @@ impl From<bool> for JSONValue {
     }
 }
 
-impl From<f64> for JSONValue {
-    /// Wraps the `f64` in the `JSONValue` enum
-    fn from(n: f64) -> Self {
-        Self::Number(n)
-    }
-}
 
 impl From<()> for JSONValue {
     /// Sets the `JSONValue` enum to the `Null` value
@@ -204,20 +250,6 @@ impl From<()> for JSONValue {
     }
 }
 
-impl From<String> for JSONValue {
-    /// Wraps the `String` in the `JSONValue` enum
-    fn from(s: String) -> Self {
-        Self::String(s)
-    }
-}
-
-impl From<&str> for JSONValue {
-    /// Creates a `String` and wraps it in the `JSONValue` enum
-    fn from(s: &str) -> Self {
-        Self::String(String::from(s))
-    }
-}
-
 /// The type of error returned by the parser
 #[derive(Debug, PartialEq)]
 pub enum ParseError {
@@ -414,7 +446,7 @@ impl JSON {
                         'n' => '\n',
                         'r' => '\r',
                         't' => '\t',
-                        _ => panic!("Shouldn't be possible!"),
+                        _ => unreachable!(),
                     };
                     result.push(ch);
                     self.increment(1);
@@ -626,6 +658,7 @@ impl JSON {
     }
 }
 
+#[cfg_attr(tarpaulin, skip)]
 #[cfg(test)]
 mod tests {
     use super::JSONValue::{Array, Number, True};