Docs: documenting public API (fixes #431) (#442)

* Docs: documenting public API

* Chore: created script to sync README

* Chore: changed subMaxLevel to 3

Makefile.js

@@ -23,6 +23,7 @@ const path = require("path");
 const NODE_MODULES = "./node_modules/",
     TEMP_DIR = "./tmp/",
     BUILD_DIR = "./build/",
+    DOCS_DIR = "./docs",
 
     // Utilities - intentional extra space at the end of each string
     MOCHA = `${NODE_MODULES}mocha/bin/_mocha `,
@@ -92,9 +93,10 @@ target.test = function() {
 };
 
 target.docs = function() {
-    echo("Generating documentation");
-    nodeCLI.exec("jsdoc", "-d jsdoc lib");
-    echo("Documentation has been output to /jsdoc");
+    echo("Syncing README.md from root with docs/README.md");
+    rm("-r", `${DOCS_DIR}/README.md`);
+    cp("README.md", DOCS_DIR);
+    echo("Done. ");
 };
 
 target.browserify = function() {

README.md

@@ -23,14 +23,101 @@ const espree = require("espree");
 const ast = espree.parse(code);
 ```
 
-There is a second argument to `parse()` that allows you to specify various options:
+## API
+
+### `parse()`
+
+`parse` parses the given code and returns a abstract syntax tree (AST). It takes two paramenter.
+
+- `code` [string]() - the code which needs to be parsed. 
+- `options (Optional)` [Object]() - read more about this [here](#options)
 
 ```javascript
 const espree = require("espree");
 
-// Optional second options argument with the following default settings
-const ast = espree.parse(code, {
+const ast = espree.parse(code, options);
+```
+
+**Example :**
+
+```js
+const ast = espree.parse('let foo = "bar"', { ecmaVersion: 6 });
+console.log(ast);
+```
+
+<details><summary>Output</summary>
+<p>
+
+```
+Node {
+  type: 'Program',
+  start: 0,
+  end: 15,
+  body: [
+    Node {
+      type: 'VariableDeclaration',
+      start: 0,
+      end: 15,
+      declarations: [Array],
+      kind: 'let'
+    }
+  ],
+  sourceType: 'script'
+}
+```
+
+</p>
+</details>
+
+### `tokenize()`
+
+`tokenize` returns the tokens of a give code. It takes two paramenter.
+
+- `code` [string]() - the code which needs to be parsed. 
+- `options (Optional)` [Object]() - read more about this [here](#options)
+
+Even if `options` is empty or undefined or `options.tokens` is `false`, it assigns it to `true` in order to get the `tokens` array
+
+**Example :**
+
+```js
+const tokens = espree.tokenize('let foo = "bar"', { ecmaVersion: 6 });
+console.log(tokens);
+```
+
+<details><summary>Output</summary>
+<p>
+
+```
+Token { type: 'Keyword', value: 'let', start: 0, end: 3 },
+Token { type: 'Identifier', value: 'foo', start: 4, end: 7 },
+Token { type: 'Punctuator', value: '=', start: 8, end: 9 },
+Token { type: 'String', value: '"bar"', start: 10, end: 15 }
+```
+
+</p>
+</details>
+
+### `version`
+
+Returns the current `espree` version
+
+### `VisitorKeys`
+
+Returns all visitor keys for traversing the AST from [eslint-visitor-keys](https://github.com/eslint/eslint-visitor-keys)
+
+### `latestEcmaVersion`
+
+Returns the latest ECMAScript supported by `espree`
+
+### `supportedEcmaVersions`
+
+Returns an array of all supported ECMAScript version 
+
+## Options 
 
+```js
+const options = {
     // attach range information to each node
     range: false,
 
@@ -62,7 +149,7 @@ const ast = espree.parse(code, {
         // enable implied strict mode (if ecmaVersion >= 5)
         impliedStrict: false
     }
-});
+}
 ```
 
 ## Esprima Compatibility Going Forward

docs/README.md

@@ -23,14 +23,101 @@ const espree = require("espree");
 const ast = espree.parse(code);
 ```
 
-There is a second argument to `parse()` that allows you to specify various options:
+## API
+
+### `parse()`
+
+`parse` parses the given code and returns a abstract syntax tree (AST). It takes two paramenter.
+
+- `code` [string]() - the code which needs to be parsed. 
+- `options (Optional)` [Object]() - read more about this [here](#options)
 
 ```javascript
 const espree = require("espree");
 
-// Optional second options argument with the following default settings
-const ast = espree.parse(code, {
+const ast = espree.parse(code, options);
+```
+
+**Example :**
+
+```js
+const ast = espree.parse('let foo = "bar"', { ecmaVersion: 6 });
+console.log(ast);
+```
+
+<details><summary>Output</summary>
+<p>
+
+```
+Node {
+  type: 'Program',
+  start: 0,
+  end: 15,
+  body: [
+    Node {
+      type: 'VariableDeclaration',
+      start: 0,
+      end: 15,
+      declarations: [Array],
+      kind: 'let'
+    }
+  ],
+  sourceType: 'script'
+}
+```
+
+</p>
+</details>
+
+### `tokenize()`
+
+`tokenize` returns the tokens of a give code. It takes two paramenter.
+
+- `code` [string]() - the code which needs to be parsed. 
+- `options (Optional)` [Object]() - read more about this [here](#options)
+
+Even if `options` is empty or undefined or `options.tokens` is `false`, it assigns it to `true` in order to get the `tokens` array
+
+**Example :**
+
+```js
+const tokens = espree.tokenize('let foo = "bar"', { ecmaVersion: 6 });
+console.log(tokens);
+```
+
+<details><summary>Output</summary>
+<p>
+
+```
+Token { type: 'Keyword', value: 'let', start: 0, end: 3 },
+Token { type: 'Identifier', value: 'foo', start: 4, end: 7 },
+Token { type: 'Punctuator', value: '=', start: 8, end: 9 },
+Token { type: 'String', value: '"bar"', start: 10, end: 15 }
+```
+
+</p>
+</details>
+
+### `version`
+
+Returns the current `espree` version
+
+### `VisitorKeys`
+
+Returns all visitor keys for traversing the AST from [eslint-visitor-keys](https://github.com/eslint/eslint-visitor-keys)
+
+### `latestEcmaVersion`
+
+Returns the latest ECMAScript supported by `espree`
+
+### `supportedEcmaVersions`
+
+Returns an array of all supported ECMAScript version 
+
+## Options 
 
+```js
+const options = {
     // attach range information to each node
     range: false,
 
@@ -62,7 +149,7 @@ const ast = espree.parse(code, {
         // enable implied strict mode (if ecmaVersion >= 5)
         impliedStrict: false
     }
-});
+}
 ```
 
 ## Esprima Compatibility Going Forward

docs/index.html

@@ -135,7 +135,7 @@
         name: 'espree',
         repo: 'eslint/espree',
         loadSidebar: true,
-        subMaxLevel: 2,
+        subMaxLevel: 3,
         maxLevel: 3,
         auto2top: true,
         search: {

package.json

@@ -52,6 +52,7 @@
     "generate-regex": "node tools/generate-identifier-regex.js",
     "test": "npm run-script lint && node Makefile.js test",
     "lint": "node Makefile.js lint",
+    "sync-docs": "node Makefile.js docs",
     "browserify": "node Makefile.js browserify",
     "generate-release": "eslint-generate-release",
     "generate-alpharelease": "eslint-generate-prerelease alpha",