More documentation

src/lib.rs

@@ -1,6 +1,27 @@
 //! # Naive JSON Parser
 //!
 //! Based on [JSON Parser with JavaScript](https://lihautan.com/json-parser-with-javascript/)
+//!
+//! This project is only concerned with parsing JSON. Serializing the [JSONValue](enum.JSONValue.html) into
+//! a native rust object is out of scope.
+//!
+//! Basic usage:
+//! ```rust
+//! use naive_json_parser::{JSON, JSONArray};
+//!
+//! // Convert the JSON string to a `JSONValue`
+//! let result = JSON::parse("[0, 1, 2]");
+//! # assert!(&result.is_ok());
+//!
+//! // Let's assume you know the JSON is valid
+//! let result = result.unwrap();
+//!
+//! // If you want the value inside of the top `JSONValue`, you
+//! // may use the `into` or `unwrap` methods
+//! let array: JSONArray = result.clone().into(); // or
+//! let array: JSONArray = result.clone().unwrap(); // or
+//! let array = JSONArray::from(result.clone());
+//! ```
 #![forbid(unsafe_code)]
 use std::collections::HashMap;
 use std::iter::FromIterator;
@@ -41,7 +62,7 @@ pub enum JSONValue {
 }
 
 impl JSONValue {
-    /// Convert the wrapped JSONValue to its simpler rust value
+    /// Convert the wrapped `JSONValue` to its simpler rust value
     ///
     /// This is a convenience method that calls the `from` method
     /// for the appropriate type.
@@ -206,7 +227,10 @@ pub enum ParseError {
     ExpectedUnicodeEscape(String),
 }
 
-/// This struct holds a little state for parsing
+/// This struct is the bulk of the parser
+///
+/// The members of the struct are private, as they
+/// are implementation details of the parser
 #[derive(Debug, PartialEq)]
 pub struct JSON {
     /// The input JSON String as a character array
@@ -571,8 +595,11 @@ impl JSON {
     /// ```rust
     /// use naive_json_parser::JSON;
     ///
-    /// // This should now be a set of nested `JSONValue` enums containing the parsed values
-    /// let parse_result = JSON::parse(r#"[1, 2.0, 3e4, "foo", {}, [], true, false, null]"#);
+    /// let json = r#"[1, 2.0, 3e4, "foo", {}, [], true, false, null]"#;
+    ///
+    /// // If valid JSON, this should now be a set of nested `JSONValue` enums containing the
+    /// // parsed values. If invalid, a `ParseError` is returned.
+    /// let parse_result = JSON::parse(json);
     /// # assert!(parse_result.is_ok(), "Parse method example failed");
     /// ```
     pub fn parse(json: &str) -> JSONResult {