remove unused vars & update docs

Author: ichiriac

docs/README.md

@@ -2,11 +2,36 @@
 
 # engine
 
+Initialise a new parser instance with the specified options
+
+Usage :
+
+```js
+var parser = require('php-parser');
+var instance = new parser({
+  parser: {
+    extractDoc: true,
+    suppressErrors: true
+  },
+  ast: {
+    withPositions: true
+  },
+  lexer: {
+    short_tags: true,
+    asp_tags: true
+  }
+});
+
+var evalAST = instance.parseEval('some php code');
+var codeAST = instance.parseCode('<?php some php code', 'foo.php');
+var tokens = instance.tokenGetAll('<?php some php code');
+```
+
 Type: Engine
 
 **Parameters**
 
--   `options` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** 
+-   `options` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** List of options
 
 **Properties**
 
@@ -17,13 +42,13 @@ Type: Engine
 
 ## parseEval
 
-parsing eval string as '$x = 1;'
+Parse an evaluating mode string (no need to open php tags)
 
 **Parameters**
 
--   `buffer`  
+-   `buffer` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** 
 
-Returns **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** 
+Returns **Program** 
 
 ## parseCode
 
@@ -54,63 +79,12 @@ Returns **Program**
 
 ## tokenGetAll
 
-split the buffer into tokens
-
-**Parameters**
-
--   `buffer`  
-
-## create
-
-Creates a new instance
-
-**Parameters**
-
--   `options` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** 
-
-Returns **Engine** 
-
-## parseEval
-
-Evaluate the buffer
-
-**Parameters**
-
--   `buffer`  
--   `options`  
-
-## parseCode
-
-Static function that parse a php code with open/close tags
-
-Sample code :
-
-```php
-<?php $x = 1;
-```
-
-Usage :
-
-```js
-var parser = require('php-parser');
-var ast = parser.parseCode('...php code...', 'foo.php');
-```
-
-**Parameters**
-
--   `buffer` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The code to be parsed
--   `filename` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Filename
--   `options` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Optional options
-
-Returns **Program** 
-
-## tokenGetAll
+Extract tokens from the specified buffer.
 
-Split the buffer into tokens
+> Note that the output tokens are _STRICLY_ similar to PHP function `token_get_all`
 
 **Parameters**
 
--   `buffer`  
--   `options`  
+-   `buffer` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** 
 
-Returns **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)>** 
+Returns **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)>** Each item can be a string or an array with following informations [token_name, text, line_number]

docs/parser.md

@@ -2,7 +2,9 @@
 
 # parser
 
-The PHP Parser class
+The PHP Parser class that build the AST tree from the lexer
+
+Type: Parser
 
 **Parameters**
 
@@ -11,11 +13,12 @@ The PHP Parser class
 
 **Properties**
 
--   `EOF` **Integer** 
--   `lexer` **Lexer** 
--   `token` **(Integer | [String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String))** 
--   `extractDoc` **[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** 
--   `debug` **[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** 
+-   `lexer` **Lexer** current lexer instance
+-   `ast` **AST** the AST factory instance
+-   `token` **(Integer | [String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String))** current token
+-   `extractDoc` **[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** should extract documentation as AST node
+-   `suppressErrors` **[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** should ignore parsing errors and continue
+-   `debug` **[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** should output debug informations
 
 ## getTokenName
 

src/index.js

@@ -34,8 +34,33 @@ function combine(src, to) {
 }
 
 /**
+ * Initialise a new parser instance with the specified options
+ *
+ * Usage :
+ * ```js
+ * var parser = require('php-parser');
+ * var instance = new parser({
+ *   parser: {
+ *     extractDoc: true,
+ *     suppressErrors: true
+ *   },
+ *   ast: {
+ *     withPositions: true
+ *   },
+ *   lexer: {
+ *     short_tags: true,
+ *     asp_tags: true
+ *   }
+ * });
+ *
+ * var evalAST = instance.parseEval('some php code');
+ * var codeAST = instance.parseCode('<?php some php code', 'foo.php');
+ * var tokens = instance.tokenGetAll('<?php some php code');
+ * ```
+ *
  * @constructor {Engine}
- * @param {Object} options
+ * @param {Object} options - List of options
+ *
  * @property {Lexer} lexer
  * @property {Parser} parser
  * @property {AST} ast
@@ -55,25 +80,28 @@ var engine = function(options) {
 };
 
 /**
- * Creates a new instance
+ * Creates a new instance (Helper)
  * @param {Object} options
  * @return {Engine}
- */
+ * @private
+*/
 engine.create = function(options) {
   return new engine(options);
 };
 
 /**
  * Evaluate the buffer
+ * @private
  */
 engine.parseEval = function(buffer, options) {
   var self = new engine(options);
   return self.parseEval(buffer);
 };
 
 /**
- * parsing eval string as '$x = 1;'
- * @return {Array}
+ * Parse an evaluating mode string (no need to open php tags)
+ * @param {String} buffer
+ * @return {Program}
  */
 engine.prototype.parseEval = function(buffer) {
   this.lexer.mode_eval = true;
@@ -83,21 +111,7 @@ engine.prototype.parseEval = function(buffer) {
 
 /**
  * Static function that parse a php code with open/close tags
- *
- * Sample code :
- * ```php
- * <?php $x = 1;
- * ```
- *
- * Usage :
- * ```js
- * var parser = require('php-parser');
- * var ast = parser.parseCode('...php code...', 'foo.php');
- * ```
- * @param {String} buffer - The code to be parsed
- * @param {String} filename - Filename
- * @param {Object} options - Optional options
- * @return {Program}
+ * @private
  */
 engine.parseCode = function(buffer, filename, options) {
   if (typeof filename === 'object') {
@@ -137,15 +151,18 @@ engine.prototype.parseCode = function(buffer, filename) {
 
 /**
  * Split the buffer into tokens
- * @return {String[]}
+ * @private
  */
 engine.tokenGetAll = function(buffer, options) {
   var self = new engine(options);
   return self.tokenGetAll(buffer);
 };
 
 /**
- * split the buffer into tokens
+ * Extract tokens from the specified buffer.
+ * > Note that the output tokens are *STRICLY* similar to PHP function `token_get_all`
+ * @param {String} buffer
+ * @return {String[]} - Each item can be a string or an array with following informations [token_name, text, line_number]
  */
 engine.prototype.tokenGetAll = function(buffer) {
   this.lexer.mode_eval = false;

src/parser.js

@@ -13,30 +13,25 @@ function isNumber(n) {
 
 
 /**
- * The PHP Parser class
- *
- * @public @constructor {Parser}
- * @property {Integer} EOF
- * @property {Lexer} lexer
- * @property {Integer|String} token
- * @property {Boolean} extractDoc
- * @property {Boolean} debug
+ * The PHP Parser class that build the AST tree from the lexer
+ * @constructor {Parser}
+ * @property {Lexer} lexer - current lexer instance
+ * @property {AST} ast - the AST factory instance
+ * @property {Integer|String} token - current token
+ * @property {Boolean} extractDoc - should extract documentation as AST node
+ * @property {Boolean} suppressErrors - should ignore parsing errors and continue
+ * @property {Boolean} debug - should output debug informations
  */
 var parser = function(lexer, ast) {
   this.lexer = lexer;
   this.ast = ast;
   this.tok = lexer.tok;
   this.EOF = lexer.EOF;
-  // Private vars, do not use directly
-  this._gracefulProxy = {};
-  this._graceful = false;
   this.token = null;
   this.prev = null;
   this.debug = false;
   this.extractDoc = false;
   this.suppressErrors = false;
-  this.lastError = false;
-  this.startAt = [];
   this.entries = {
     'SCALAR': [
       this.tok.T_CONSTANT_ENCAPSED_STRING,