Add documentation to all modules

.gitignore

@@ -1,3 +1,6 @@
+# Ignore build output
+/out
+
 # Ignore Aptana Studio project files
 .project
 

LICENSE.md

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2013 Chris Broome
+Copyright (c) 2015 Chris Broome
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

lib/parser.js

@@ -1,7 +1,9 @@
 'use strict';
 var
   _ = require('lodash'),
-  errors = require('./parser/errors'),
+  EndOfInputError = require('./parser/errors/end-of-input-error'),
+  TypeMismatchError = require('./parser/errors/type-mismatch-error'),
+  UnexpectedEndOfInputError = require('./parser/errors/unexpected-end-of-input-error'),
   ArrayNode = require('./parser/nodes/array-node'),
   FalseNode = require('./parser/nodes/false-node'),
   NullNode = require('./parser/nodes/null-node'),
@@ -39,41 +41,73 @@ function Parser(options) {
     self.assertEndOfInput();
   });
 }
-_.extend(Parser.prototype, {
+Parser.prototype = {
 
+  /**
+   * Adds an error to the internal error stack
+   * @param {Error} err
+   * @returns {boolean}
+   */
   error: function error(err) {
     this._errors.push(err);
     return false;
   },
 
-  // advances the iterator
+  /**
+   * Advances the iterator
+   */
   next: function next() {
     this._tokenPointer += 1;
   },
 
+  /**
+   * Get the internal error stack
+   * @returns {Array}
+   */
   getErrors: function getErrors() {
     return this._errors;
   },
 
+  /**
+   * Tests whether or not we should ignore this type of token
+   * @param {string} tokenType
+   * @returns {boolean}
+   */
   ignoreTokens: function ignoreTokens(tokenType) {
     return this._ignoreTokens.indexOf(tokenType) >= 0;
   },
 
+  /**
+   * Get the current token in the token stack
+   * @returns {Token}
+   */
   currentToken: function currentToken() {
     return this._tokens[this._tokenPointer];
   },
 
+  /**
+   * Parses an object token
+   * @returns {Object|null}
+   */
   object: function object() {
     return this.parseContainer(ObjectNode, 'pair');
   },
 
+  /**
+   * Parses a key/value pair
+   * @returns {KeyValuePairNode}
+   */
   pair: function pair() {
     var key = this.parseString(), value;
     this.nextTerminalToken(':');
     value = this.value();
     return new PairNode({key: key, value: value});
   },
 
+  /**
+   * Parses a value
+   * @returns {*}
+   */
   value: function value() {
     var token = this.currentToken();
     if (!this.assertNotEndOfInput('value')) return null;
@@ -91,26 +125,50 @@ _.extend(Parser.prototype, {
     }
   },
 
+  /**
+   * Parses an array
+   * @returns {Object|null}
+   */
   array: function array() {
     return this.parseContainer(ArrayNode, 'value');
   },
 
+  /**
+   * Parses the 'false' expression
+   * @returns {Object|null}
+   */
   parseFalse: function parseFalse() {
     return this.parseTerminal(FalseNode);
   },
 
+  /**
+   * Parses a number
+   * @returns {Object|null}
+   */
   parseNumber: function parseNumber() {
     return this.parseTerminal(NumberNode);
   },
 
+  /**
+   * Parses null
+   * @returns {Object|null}
+   */
   parseNull: function parseNull() {
     return this.parseTerminal(NullNode);
   },
 
+  /**
+   * Parses a string
+   * @returns {Object|null}
+   */
   parseString: function parseString() {
     return this.parseTerminal(StringNode);
   },
 
+  /**
+   * Parses the 'true' literal expression
+   * @returns {Object|null}
+   */
   parseTrue: function parseTrue(){
     return this.parseTerminal(TrueNode);
   },
@@ -185,19 +243,19 @@ _.extend(Parser.prototype, {
   },
 
   assertEndOfInput: function assertEndOfInput() {
-    return this.assertCurrentToken(tokenDoesNotExist, errors.EndOfInputError);
+    return this.assertCurrentToken(tokenDoesNotExist, EndOfInputError);
   },
 
   assertNotEndOfInput: function assertNotEndOfInput() {
     var expectedValues = _.drop(arguments, 0);
-    return this.assertCurrentToken(tokenExists, errors.UnexpectedEndOfInputError, expectedValues);
+    return this.assertCurrentToken(tokenExists, UnexpectedEndOfInputError, expectedValues);
   },
 
   assertTypeEquals: function assertTypeEquals(type) {
-    return this.assertCurrentToken(tokenTypeMatches, errors.TypeMismatchError, type);
+    return this.assertCurrentToken(tokenTypeMatches, TypeMismatchError, type);
   }
 
-});
+};
 
 function tokenDoesNotExist(token) {
   return !token;

lib/parser/errors/end-of-input-error.js

@@ -0,0 +1,19 @@
+var
+  util = require('util'),
+  ErrorBase = require('./error-base');
+
+util.inherits(EndOfInputError, ErrorBase);
+
+/**
+ * @type {EndOfInputError}
+ */
+module.exports = EndOfInputError;
+
+/**
+ * @param {Token} token
+ * @constructor
+ */
+function EndOfInputError(token) {
+  ErrorBase.call(this, 'Expected end of input at ' + token.toLineString() + '. Found ' + token.type + ' instead');
+  this.token = token;
+}

lib/parser/errors/error-base.js

@@ -0,0 +1,23 @@
+var
+  util = require('util');
+
+util.inherits(ErrorBase, Error);
+
+/**
+ * @type {ErrorBase}
+ */
+module.exports = ErrorBase;
+
+/**
+ * Abstract base error
+ * @param {String} [message]
+ * @constructor
+ * @abstract
+ */
+function ErrorBase(message) {
+  var ctor = this.constructor;
+  Error.captureStackTrace(this, ctor);
+  this.message = message;
+  this.name = ctor.name;
+  this.statusCode = 500;
+}

lib/parser/errors/type-mismatch-error.js

@@ -0,0 +1,21 @@
+var
+  util = require('util'),
+  ErrorBase = require('./error-base');
+
+util.inherits(TypeMismatchError, ErrorBase);
+
+/**
+ * @type {TypeMismatchError}
+ */
+module.exports = TypeMismatchError;
+
+/**
+ * @param {string} expectedType
+ * @param {Token} token
+ * @constructor
+ */
+function TypeMismatchError(expectedType, token) {
+  ErrorBase.call(this, token.toString() + ': expected ' + expectedType + ' actual type seen was ' + token.type);
+  this.token = token;
+  this.expectedType = expectedType;
+}

lib/parser/errors/unexpected-end-of-input-error.js

@@ -0,0 +1,18 @@
+var
+  util = require('util'),
+  ErrorBase = require('./error-base');
+
+util.inherits(UnexpectedEndOfInputError, ErrorBase);
+
+/**
+ * @type {UnexpectedEndOfInputError}
+ */
+module.exports = UnexpectedEndOfInputError;
+
+/**
+ * @param {*} expectedValues
+ * @constructor
+ */
+function UnexpectedEndOfInputError(expectedValues) {
+  ErrorBase.call(this, 'Unexpected end of input reached. Expected ' + expectedValues.join(' '));
+}

lib/parser/nodes/array-node.js

@@ -6,12 +6,13 @@ var
 
 util.inherits(ArrayNode, ContainerNode);
 
+/**
+ * @type {ArrayNode}
+ */
 module.exports = ArrayNode;
 
 /**
- * @class
- * @type {Object}
- * @param {Object} options
+ * @param {object} options
  * @constructor
  */
 function ArrayNode(options) {

lib/parser/nodes/container-node.js

@@ -6,12 +6,13 @@ var
 
 util.inherits(ContainerNode, NodeBase);
 
+/**
+ * @type {ContainerNode}
+ */
 module.exports = ContainerNode;
 
 /**
- * @class
- * @type {Object}
- * @param {Object} options
+ * @param {object} options
  * @constructor
  */
 function ContainerNode(options) {

lib/parser/nodes/false-node.js

@@ -6,12 +6,19 @@ var
 
 util.inherits(FalseNode, TerminalNode);
 
+/**
+ * @type {FalseNode}
+ */
 module.exports = FalseNode;
 
-FalseNode.type = 'false';
+/**
+ * @param {object} options
+ * @constructor
+ */
 function FalseNode(options) {
   var opts = options || {};
   TerminalNode.call(this, opts);
   this.type = 'false';
   this.value = false;
 }
+FalseNode.type = 'false';

lib/parser/nodes/list-node.js

@@ -6,12 +6,13 @@ var
 
 util.inherits(ListNode, NodeBase);
 
+/**
+ * @type {ListNode}
+ */
 module.exports = ListNode;
 
 /**
- * @class
- * @type {Object}
- * @param {Object} options
+ * @param {object} options
  * @constructor
  */
 function ListNode(options) {

lib/parser/nodes/node-base.js

@@ -1,11 +1,15 @@
 'use strict';
 
+/**
+ * @type {NodeBase}
+ */
 module.exports = NodeBase;
 
+/**
+ * @param {object} options
+ * @constructor
+ */
 function NodeBase(options) {
   var opts = options || {};
   this.type = opts.type;
 }
-NodeBase.prototype = {
-
-};

lib/parser/nodes/null-node.js

@@ -6,12 +6,19 @@ var
 
 util.inherits(NullNode, TerminalNode);
 
+/**
+ * @type {NullNode}
+ */
 module.exports = NullNode;
 
-NullNode.type = 'null';
+/**
+ * @param {object} options
+ * @constructor
+ */
 function NullNode(options) {
   var opts = options || {};
   TerminalNode.call(this, opts);
   this.type = 'null';
   this.value = null;
 }
+NullNode.type = 'null';