documentation updates

Cargo.lock

@@ -1,4 +1,4 @@
 [[package]]
-name = "Boa"
+name = "boa"
 version = "0.1.1"
 

Cargo.toml

@@ -1,5 +1,5 @@
 [package]
-name = "Boa"
+name = "boa"
 version = "0.1.1"
 authors = ["Jason Williams <jase.williams@gmail.com>"]
 description = "Boa is a Javascript lexer, parser and Just-in-Time compiler written in Rust. Currently, it has support for some of the language."

src/lib/syntax/ast/pos.rs

@@ -1,5 +1,9 @@
 #[derive(Clone, PartialEq, Debug)]
-// A position in Javascript source code
+/// A position in the Javascript source code
+/// Stores both the column number and the line number
+///
+/// ## Similar Implementations
+/// [V8: Location](https://cs.chromium.org/chromium/src/v8/src/parsing/scanner.h?type=cs&q=isValid+Location&g=0&l=216)
 pub struct Position {
     // Column number
     pub column_number: u64,
@@ -8,7 +12,23 @@ pub struct Position {
 }
 
 impl Position {
-    // Create a new position
+    /// Create a new position, positions are usually created by Tokens..
+    ///
+    /// # Arguments
+    ///
+    /// * `line_number` - The line number the token starts at
+    /// * `column_number` - The column number the token starts at
+    ///
+    /// # Example from Token
+    ///
+    /// ```
+    ///  pub fn new(data: TokenData, line_number: u64, column_number: u64) -> Token {
+    ///     Token {
+    ///         data: data,
+    ///         pos: Position::new(line_number, column_number),
+    ///     }
+    /// }
+    /// ```
     pub fn new(line_number: u64, column_number: u64) -> Position {
         Position {
             line_number: line_number,

src/lib/syntax/lexer.rs

@@ -1,3 +1,7 @@
+//! A lexical analyzer for JavaScript source code.
+//!
+//! The Lexer splits its input source code into a sequence of input elements called tokens, represented by the [Token](../ast/token/struct.Token.html) structure.
+//! It also removes whitespace and comments and attaches them to the next token.
 use std::char::from_u32;
 use std::error;
 use std::fmt;
@@ -54,7 +58,7 @@ macro_rules! op {
     });
 }
 
-// Defining an error type
+/// An error that occurred during lexing or compiling of the source input.
 #[derive(Debug, Clone)]
 pub struct LexerError {
     details: String,
@@ -74,7 +78,6 @@ impl fmt::Display for LexerError {
     }
 }
 
-// This is important for other errors to wrap this one.
 impl error::Error for LexerError {
     fn description(&self) -> &str {
         &self.details
@@ -86,7 +89,7 @@ impl error::Error for LexerError {
     }
 }
 
-/// A javascript Lexer
+/// A lexical analyzer for JavaScript source code
 pub struct Lexer<'a> {
     // The list fo tokens generated so far
     pub tokens: Vec<Token>,
@@ -99,6 +102,19 @@ pub struct Lexer<'a> {
 }
 
 impl<'a> Lexer<'a> {
+    /// Returns a Lexer with a buffer inside
+    ///
+    /// # Arguments
+    ///
+    /// * `buffer` - A string slice that holds the source code.   
+    /// The buffer needs to have a lifetime as long as the Lexer instance itself
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// let buffer = read_to_string("yourSourceCode.js").unwrap();
+    /// let lexer = Lexer::new(&buffer);
+    /// ```
     pub fn new(buffer: &'a str) -> Lexer<'a> {
         Lexer {
             tokens: Vec::new(),

src/lib/syntax/mod.rs

@@ -1,6 +1,6 @@
 /// The Javascript Abstract Syntax Tree
 pub mod ast;
-/// Parses a string stream into a sequence of tokens
+/// Lexical analysis (tokenizing/lexing).
 pub mod lexer;
 // Parses a sequence of tokens into expressions
 pub mod parser;