CLEANUP: Documentation and public interface.

* Added missing docs for public methods or functions.
* Made private methods or functions that didn't need to be exposed.
* Cleaned up spelling and grammar on some of the docstrings.

src/ast/mod.rs

@@ -13,7 +13,6 @@
 //  limitations under the License.
 
 //! The definitions of the ucg AST and Tokens.
-
 use std;
 use std::borrow::Borrow;
 use std::cmp::Eq;
@@ -626,6 +625,7 @@ pub enum BinaryExprType {
     Div,
 }
 
+/// CompareType signals the type of a comparison for a binary expression.
 #[derive(Debug, PartialEq, Clone)]
 pub enum CompareType {
     Equal,
@@ -636,6 +636,7 @@ pub enum CompareType {
     LTEqual,
 }
 
+/// ComparisonDef Represents a comparison between two expressions.
 #[derive(Debug, PartialEq, Clone)]
 pub struct ComparisonDef {
     pub kind: CompareType,
@@ -676,12 +677,14 @@ pub struct ListDef {
     pub pos: Position,
 }
 
+/// ListOpType represents the type of list operation for a ListOpDef.
 #[derive(Debug, PartialEq, Clone)]
 pub enum ListOpType {
     Map,
     Filter,
 }
 
+/// ListOpDef implements the list operations in the UCG AST.
 #[derive(Debug, PartialEq, Clone)]
 pub struct ListOpDef {
     pub typ: ListOpType,

src/build/mod.rs

@@ -286,13 +286,14 @@ impl From<String> for Val {
 /// Defines a set of values in a parsed file.
 type ValueMap = HashMap<Positioned<String>, Rc<Val>>;
 
+/// AssertCollector collects the results of assertions in the UCG AST.
 pub struct AssertCollector {
     pub success: bool,
     pub summary: String,
     pub failures: String,
 }
 
-/// Handles building ucg code.
+/// Builder handles building ucg code.
 pub struct Builder {
     root: PathBuf,
     validate_mode: bool,
@@ -432,6 +433,7 @@ impl Builder {
         Ok(())
     }
 
+    /// Evaluate an input string as UCG.
     pub fn eval_string(&mut self, input: &str) -> Result<Rc<Val>, Box<Error>> {
         match parse(Span::new(input)) {
             Ok(stmts) => {
@@ -453,18 +455,13 @@ impl Builder {
         }
     }
 
-    /// Builds a string of ucg syntax.
-    pub fn build_file_string(&mut self, input: String) -> BuildResult {
-        self.last = Some(try!(self.eval_string(&input)));
-        Ok(())
-    }
-
     /// Builds a ucg file at the named path.
     pub fn build_file(&mut self, name: &str) -> BuildResult {
         let mut f = try!(File::open(name));
         let mut s = String::new();
         try!(f.read_to_string(&mut s));
-        self.build_file_string(s)
+        self.last = Some(try!(self.eval_string(&s)));
+        Ok(())
     }
 
     fn build_import(&mut self, def: &ImportDef) -> Result<Rc<Val>, Box<Error>> {

src/build/test.rs

@@ -803,7 +803,7 @@ fn test_let_statement() {
 #[test]
 fn test_build_file_string() {
     let mut b = Builder::new(std::env::current_dir().unwrap());
-    b.build_file_string("let foo = 1;".to_string()).unwrap();
+    b.eval_string("let foo = 1;").unwrap();
     let key = value_node!("foo".to_string(), 1, 0);
     assert!(b.out.contains_key(&key));
 }

src/convert/env.rs

@@ -12,7 +12,7 @@
 //  See the License for the specific language governing permissions and
 //  limitations under the License.
 
-//! An environment variable converter.
+//! Contains code for converting a UCG Val into the environment variable output target.
 use std::io::Write;
 use std::rc::Rc;
 
@@ -20,7 +20,8 @@ use ast::Positioned;
 use build::Val;
 use convert::traits::{Converter, Result};
 
-/// EnvConverter implements the conversion logic for converting a Val into a set of environment variables.
+/// EnvConverter implements the conversion logic for converting a Val into a
+/// set of environment variables.
 pub struct EnvConverter {}
 
 impl EnvConverter {

src/convert/flags.rs

@@ -19,7 +19,8 @@ use std::rc::Rc;
 use build::Val;
 use convert::traits::{Converter, Result};
 
-/// FlagConverter implements the conversion logic for converting a Val into a set of command line flags.
+/// FlagConverter implements the conversion logic for converting a Val into a set
+/// of command line flags.
 pub struct FlagConverter {}
 
 impl FlagConverter {

src/lib.rs

@@ -17,7 +17,7 @@
 //!
 //! Ucg defines a common grammar for describing a collection of configuration values.
 //! ucg allows you to specify configuration values with a syntax that that is immutable,
-//! comoposable with copy-on-write semantics, and safe.
+//! composable, with copy-on-write semantics, and safe.
 //!
 //! ## Example
 //!

src/parse/mod.rs

@@ -63,6 +63,7 @@ macro_rules! trace_nom {
         }
     };
 }
+
 fn symbol_to_value(s: &Token) -> ParseResult<Value> {
     Ok(Value::Symbol(value_node!(
         s.fragment.to_string(),
@@ -134,6 +135,7 @@ fn triple_to_number(v: (Option<Token>, Option<Token>, Option<Token>)) -> ParseRe
     return Ok(Value::Float(value_node!(f, pref_pos)));
 }
 
+/// alt_peek conditionally runs a combinator if a lookahead combinator matches.
 macro_rules! alt_peek {
     (__inner $i:expr, $peekrule:ident!( $($peekargs:tt)* ) => $parserule:ident | $($rest:tt)* ) => (
         alt_peek!(__inner $i, $peekrule!($($peekargs)*) => call!($parserule) | $($rest)* )
@@ -291,7 +293,6 @@ named!(field_list<TokenIter, FieldList, error::Error>,
 );
 
 named!(
-    #[doc="Capture a tuple of named fields with values. {<field>=<value>,...}"],
     tuple<TokenIter, Value, error::Error>,
     map_res!(
         do_parse!(
@@ -334,7 +335,7 @@ named!(empty_value<TokenIter, Value, error::Error>,
     )
 );
 
-named!(pub compound_value<TokenIter, Value, error::Error>,
+named!(compound_value<TokenIter, Value, error::Error>,
     alt_peek!(
         punct!("[") => trace_nom!(list_value) | 
         punct!("{") => trace_nom!(tuple)
@@ -350,7 +351,7 @@ named!(scalar_value<TokenIter, Value, error::Error>,
     )
 );
 
-named!(pub value<TokenIter, Value, error::Error>,
+named!(value<TokenIter, Value, error::Error>,
     alt!(
         trace_nom!(selector_value)
         | trace_nom!(compound_value)
@@ -733,7 +734,7 @@ named!(list_op_expression<TokenIter, Expression, error::Error>,
     )
 );
 
-named!(pub non_op_expression<TokenIter, Expression, error::Error>,
+named!(non_op_expression<TokenIter, Expression, error::Error>,
     alt!(trace_nom!(list_op_expression) |
          trace_nom!(macro_expression) |
          trace_nom!(format_expression) |
@@ -744,7 +745,7 @@ named!(pub non_op_expression<TokenIter, Expression, error::Error>,
          trace_nom!(simple_expression))
 );
 
-named!(pub expression<TokenIter, Expression, error::Error>,
+named!(expression<TokenIter, Expression, error::Error>,
     alt_complete!(trace_nom!(op_expression) | trace_nom!(non_op_expression))
 );
 
@@ -752,7 +753,7 @@ fn expression_to_statement(v: Expression) -> ParseResult<Statement> {
     Ok(Statement::Expression(v))
 }
 
-named!(pub expression_statement<TokenIter, Statement, error::Error>,
+named!(expression_statement<TokenIter, Statement, error::Error>,
     map_res!(
         terminated!(trace_nom!(expression), punct!(";")),
         expression_to_statement

src/parse/precedence.rs

@@ -11,6 +11,9 @@
 //  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 //  See the License for the specific language governing permissions and
 //  limitations under the License.
+
+//! Bottom up parser for precedence parsing of expressions separated by binary
+//! operators.
 use std;
 
 use nom::{ErrorKind, IResult, InputIter, InputLength, Slice};
@@ -20,6 +23,7 @@ use ast::*;
 use error;
 use tokenizer::TokenIter;
 
+/// Defines the intermediate stages of our bottom up parser for precedence parsing.
 #[derive(Debug, PartialEq, Clone)]
 pub enum Element {
     Expr(Expression),
@@ -27,7 +31,7 @@ pub enum Element {
     CompareOp(CompareType),
 }
 
-named!(pub math_op_type<TokenIter, Element, error::Error>,
+named!(math_op_type<TokenIter, Element, error::Error>,
     alt!(
         do_parse!(punct!("+") >> (Element::MathOp(BinaryExprType::Add))) |
         do_parse!(punct!("-") >> (Element::MathOp(BinaryExprType::Sub))) |
@@ -180,19 +184,19 @@ macro_rules! do_binary_expr {
     };
 }
 
-named!(pub sum_expression<OpListIter, Expression, error::Error>,
+named!(sum_expression<OpListIter, Expression, error::Error>,
     do_binary_expr!(
         parse_sum_operator,
         alt!(trace_nom!(product_expression) | trace_nom!(parse_expression)))
 );
 
-named!(pub product_expression<OpListIter, Expression, error::Error>,
+named!(product_expression<OpListIter, Expression, error::Error>,
     do_binary_expr!(
        parse_product_operator,
     trace_nom!(parse_expression))
 );
 
-named!(pub math_expression<OpListIter, Expression, error::Error>,
+named!(math_expression<OpListIter, Expression, error::Error>,
     alt!(trace_nom!(sum_expression) | trace_nom!(product_expression))
 );
 
@@ -209,7 +213,7 @@ fn tuple_to_compare_expression(
     }))
 }
 
-named!(pub compare_op_type<TokenIter, Element, error::Error>,
+named!(compare_op_type<TokenIter, Element, error::Error>,
     alt!(
         do_parse!(punct!("==") >> (Element::CompareOp(CompareType::Equal))) |
         do_parse!(punct!("!=") >> (Element::CompareOp(CompareType::NotEqual))) |
@@ -245,7 +249,7 @@ fn parse_compare_operator(i: OpListIter) -> IResult<OpListIter, CompareType, err
     )));
 }
 
-named!(pub compare_expression<OpListIter, Expression, error::Error>,
+named!(compare_expression<OpListIter, Expression, error::Error>,
     map_res!(
         do_parse!(
             left: alt!(trace_nom!(math_expression) | trace_nom!(parse_expression)) >>
@@ -258,8 +262,8 @@ named!(pub compare_expression<OpListIter, Expression, error::Error>,
     )
 );
 
-// Implement nom::Input Length and nom::Slice for OpListIter.
-pub fn parse_operand_list(i: TokenIter) -> NomResult<Vec<Element>> {
+/// Parse a list of expressions separated by operators into a Vec<Element>.
+fn parse_operand_list(i: TokenIter) -> NomResult<Vec<Element>> {
     // 1. First try to parse a non_op_expression,
     let mut _i = i.clone();
     let mut list = Vec::new();
@@ -390,6 +394,7 @@ impl<'a> InputIter for OpListIter<'a> {
     }
 }
 
+/// Parse a binary operator expression.
 pub fn op_expression(i: TokenIter) -> NomResult<Expression> {
     let preparse = parse_operand_list(i.clone());
     match preparse {

src/tokenizer/mod.rs

@@ -420,6 +420,9 @@ pub fn tokenize(input: Span) -> Result<Vec<Token>, (Position, nom::ErrorKind)> {
     Ok(out)
 }
 
+/// Clones a token.
+///
+/// This is necessary to allow the match_type and match_token macros to work.
 pub fn token_clone(t: &Token) -> Result<Token, error::Error> {
     Ok(t.clone())
 }