Add document

parser/.travis.yml

@@ -2,3 +2,8 @@ language: rust
 rust:
         - 1.0.0
         - nightly
+env:
+  global:
+    - secure: ZUcdcbS8xbpdII9FSPx7VtoVhEkJhWL2Hb75tDlKDHNhfXqmt1NyB9q/2qXJ5Ulp4MnYXwsI8LsDloR6gvdB4xElay3smuF/neGvMjrqcB15/2p0MSQ+kZjMsNB6mlb5kAlm8ahduXIscppmw/V+m5hn3Vo+RQz/Ng+pzv0nc8KEXPMYrfRFg+a7FaeIbRbb8ir9EfflUSqArLq2hbi2WdhM3hFMcCIAUt6DD4x5ubjEg60OnIof5FDu0mXMXzQvUfHWOeYnsNcD/DLyDnm6FuQEzk37M4EB8op2SdBUeQMQ5abR3i2rd//DZpbTTEjud0PseWohGAwTwL2aoFrqs7uYQMx+vcGlOzAyDUm4VemVUa3F2BECdzU5BiujcKOITJEVUYWongld93arQq34FuXG/TO/T1XrerxfG6LTkTkKS5Vz7W8z6Rloa99WrQLJg1ZJP6itEU7G7KsDFVgRhsg7rz4/dV/2+cV4UvIwd4HlGXKCFlH0SClqvM3/7i/qqCD0689SJW6Zip+ly38MXlGy2s/AmReEasXvFer9JkOEIuPa8QTBNAjDlw7bWXi6neQWBIZU1VhZcSssnrVmEFN8fNklShzpw5DyKCv8jPTx2O6Dw8B/LgIK8uo+eaTXiO6zz/T1c/qEdsYslvxPA2D3F+ONpPU7238ykT4eRog=
+after_script:
+  - curl http://www.rust-ci.org/artifacts/put?t=$RUSTCI_TOKEN | sh

parser/src/lib.rs

@@ -1,3 +1,42 @@
+// Copyright 2015, Yuheng Chen. See the LICENSE file at the top-level
+// directory of this distribution.
+
+//! YAML 1.2 implementation in pure Rust.
+//!
+//! # Usage
+//!
+//! This crate is [on github](https://github.com/chyh1990/yaml-rust) and can be
+//! used by adding `yaml-rust` to the dependencies in your project's `Cargo.toml`.
+//!
+//! ```toml
+//! [dependencies.yaml-rust]
+//! git = "https://github.com/chyh1990/yaml-rust.git"
+//! ```
+//!
+//! And this in your crate root:
+//!
+//! ```rust
+//! extern crate yaml_rust;
+//! ```
+//!
+//! Parse a string into `Vec<Yaml>` and then serialize it as a YAML string.
+//!
+//! # Examples
+//!
+//! ```
+//! use yaml_rust::{YamlLoader, YamlEmitter};
+//!
+//! let docs = YamlLoader::load_from_str("[1, 2, 3]").unwrap();
+//! let doc = &docs[0]; // select the first document
+//! assert_eq!(doc[0].as_i64().unwrap(), 1); // access elements by index
+//! 
+//! let mut out_str = String::new();
+//! let mut emitter = YamlEmitter::new(&mut out_str);
+//! emitter.dump(doc).unwrap(); // dump the YAML object to a String
+//!
+//! ```
+
+
 pub mod yaml;
 pub mod scanner;
 pub mod parser;

parser/src/parser.rs

@@ -3,7 +3,7 @@ use std::collections::HashMap;
 // use yaml::*;
 
 #[derive(Clone, Copy, PartialEq, Debug, Eq)]
-pub enum State {
+enum State {
     StreamStart,
     ImplicitDocumentStart,
     DocumentStart,
@@ -30,21 +30,24 @@ pub enum State {
     End
 }
 
+/// `Event` is used with the low-level event base parsing API,
+/// see `EventReceiver` trait.
 #[derive(Clone, PartialEq, Debug, Eq)]
 pub enum Event {
+    /// Reserved for internal use
     NoEvent,
     StreamStart,
     StreamEnd,
     DocumentStart,
     DocumentEnd,
-    // anchor_id
+    /// Refer to an anchor ID
     Alias(usize),
-    // value, style, anchor_id, tag
+    /// Value, style, anchor_id, tag
     Scalar(String, TScalarStyle, usize, Option<TokenType>),
-    // anchor_id
+    /// Anchor ID
     SequenceStart(usize),
     SequenceEnd,
-    // anchor_id
+    /// Anchor ID
     MappingStart(usize),
     MappingEnd
 }

parser/src/yaml.rs

@@ -6,20 +6,44 @@ use std::mem;
 use parser::*;
 use scanner::{TScalarStyle, ScanError, TokenType};
 
+/// An YAML node is store as this `Yaml` enumeration, it provides an easy way to
+/// access your YAML document.
+/// 
+/// # Examples
+/// 
+/// ```
+/// use yaml_rust::Yaml;
+/// let foo = Yaml::from_str("-123"); // convert the string to the appropriate YAML type
+/// assert_eq!(foo.as_i64().unwrap(), -123);
+/// 
+/// // iterator over an Array
+/// let vec = Yaml::Array(vec![Yaml::Integer(1), Yaml::Integer(2)]);
+/// for v in vec.as_vec().unwrap() {
+///     assert!(v.as_i64().is_some());
+/// }
+/// ```
 #[derive(Clone, PartialEq, PartialOrd, Debug, Eq, Ord)]
 pub enum Yaml {
     /// float types are stored as String, and parsed on demand.
     /// Note that f64 does NOT implement Eq trait and can NOT be stored in BTreeMap
     Real(string::String),
+    /// Yaml int is stored as i64.
     Integer(i64),
+    /// Yaml scalar.
     String(string::String),
+    /// Yaml bool, e.g. `true` or `false`.
     Boolean(bool),
+    /// Yaml array, can be access as a `Vec`.
     Array(self::Array),
+    /// Yaml hash, can be access as a `BTreeMap`.
     Hash(self::Hash),
+    /// Alias, not fully supported yet.
     Alias(usize),
+    /// Yaml bool, e.g. `null` or `~`.
     Null,
-    /// Access non-exist node by Index trait will return BadValue.
+    /// Access non-exist node by Index trait will return `BadValue`.
-    /// This simplifies error handling of user.
+    /// This simplifies error handling of user. Invalid type conversion
+    /// also return `BadValue`.
     BadValue,
 }