feat: Vue Support

Thanks to @batje, documentation.js now supports Vue! .vue files are parsed for their JavaScript contents by default.
documentationjs · Apr 20, 2018 · f60d90c · bodia-uz · Apr 23, 2018 · batje
1 parent 542031e
commit f60d90c
Show file tree

Hide file tree

Showing 9 changed files with 355 additions and 2 deletions.
diff --git a/README.md b/README.md
@@ -14,7 +14,7 @@
 [![Coverage Status](https://coveralls.io/repos/github/documentationjs/documentation/badge.svg?branch=master)](https://coveralls.io/github/documentationjs/documentation?branch=master)
 [![Inline docs](http://inch-ci.org/github/documentationjs/documentation.svg?branch=master&style=flat-square)](http://inch-ci.org/github/documentationjs/documentation)
 
-* Supports modern JavaScript: ES5, ES2017, JSX, and [Flow](http://flowtype.org/) type annotations.
+* Supports modern JavaScript: ES5, ES2017, JSX, Vue and [Flow](http://flowtype.org/) type annotations.
 * Infers parameters, types, membership, and more. Write less documentation: let the computer write it for you.
 * Integrates with GitHub to link directly from documentation to the code it refers to.
 * Customizable output: HTML, JSON, Markdown, and more

diff --git a/__tests__/__snapshots__/test.js.snap b/__tests__/__snapshots__/test.js.snap
@@ -1,5 +1,282 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
+exports[`Vue file 1`] = `
+Array [
+  Object {
+    "augments": Array [],
+    "context": Object {
+      "loc": SourceLocation {
+        "end": Position {
+          "column": 1,
+          "line": 19,
+        },
+        "start": Position {
+          "column": 0,
+          "line": 7,
+        },
+      },
+    },
+    "description": Object {
+      "children": Array [
+        Object {
+          "children": Array [
+            Object {
+              "position": Position {
+                "end": Object {
+                  "column": 29,
+                  "line": 1,
+                  "offset": 28,
+                },
+                "indent": Array [],
+                "start": Object {
+                  "column": 1,
+                  "line": 1,
+                  "offset": 0,
+                },
+              },
+              "type": "text",
+              "value": "This Vue Component is a test",
+            },
+          ],
+          "position": Position {
+            "end": Object {
+              "column": 29,
+              "line": 1,
+              "offset": 28,
+            },
+            "indent": Array [],
+            "start": Object {
+              "column": 1,
+              "line": 1,
+              "offset": 0,
+            },
+          },
+          "type": "paragraph",
+        },
+      ],
+      "position": Object {
+        "end": Object {
+          "column": 29,
+          "line": 1,
+          "offset": 28,
+        },
+        "start": Object {
+          "column": 1,
+          "line": 1,
+          "offset": 0,
+        },
+      },
+      "type": "root",
+    },
+    "errors": Array [],
+    "examples": Array [],
+    "loc": SourceLocation {
+      "end": Position {
+        "column": 3,
+        "line": 6,
+      },
+      "start": Position {
+        "column": 0,
+        "line": 3,
+      },
+    },
+    "members": Object {
+      "events": Array [],
+      "global": Array [],
+      "inner": Array [],
+      "instance": Array [],
+      "static": Array [],
+    },
+    "name": "vue.input",
+    "namespace": "vue.input",
+    "params": Array [],
+    "path": Array [
+      Object {
+        "kind": undefined,
+        "name": "vue.input",
+      },
+    ],
+    "properties": Array [],
+    "returns": Array [
+      Object {
+        "description": Object {
+          "children": Array [
+            Object {
+              "children": Array [
+                Object {
+                  "position": Position {
+                    "end": Object {
+                      "column": 21,
+                      "line": 1,
+                      "offset": 20,
+                    },
+                    "indent": Array [],
+                    "start": Object {
+                      "column": 1,
+                      "line": 1,
+                      "offset": 0,
+                    },
+                  },
+                  "type": "text",
+                  "value": "vue-tested component",
+                },
+              ],
+              "position": Position {
+                "end": Object {
+                  "column": 21,
+                  "line": 1,
+                  "offset": 20,
+                },
+                "indent": Array [],
+                "start": Object {
+                  "column": 1,
+                  "line": 1,
+                  "offset": 0,
+                },
+              },
+              "type": "paragraph",
+            },
+          ],
+          "position": Object {
+            "end": Object {
+              "column": 21,
+              "line": 1,
+              "offset": 20,
+            },
+            "start": Object {
+              "column": 1,
+              "line": 1,
+              "offset": 0,
+            },
+          },
+          "type": "root",
+        },
+        "title": "returns",
+        "type": Object {
+          "name": "vue-tested",
+          "type": "NameExpression",
+        },
+      },
+    ],
+    "sees": Array [],
+    "tags": Array [
+      Object {
+        "description": "vue-tested component",
+        "lineNumber": 2,
+        "title": "returns",
+        "type": Object {
+          "name": "vue-tested",
+          "type": "NameExpression",
+        },
+      },
+    ],
+    "throws": Array [],
+    "todos": Array [],
+  },
+  Object {
+    "augments": Array [],
+    "context": Object {
+      "loc": SourceLocation {
+        "end": Position {
+          "column": 3,
+          "line": 17,
+        },
+        "start": Position {
+          "column": 2,
+          "line": 14,
+        },
+      },
+    },
+    "description": Object {
+      "children": Array [
+        Object {
+          "children": Array [
+            Object {
+              "position": Position {
+                "end": Object {
+                  "column": 17,
+                  "line": 1,
+                  "offset": 16,
+                },
+                "indent": Array [],
+                "start": Object {
+                  "column": 1,
+                  "line": 1,
+                  "offset": 0,
+                },
+              },
+              "type": "text",
+              "value": "This is a number",
+            },
+          ],
+          "position": Position {
+            "end": Object {
+              "column": 17,
+              "line": 1,
+              "offset": 16,
+            },
+            "indent": Array [],
+            "start": Object {
+              "column": 1,
+              "line": 1,
+              "offset": 0,
+            },
+          },
+          "type": "paragraph",
+        },
+      ],
+      "position": Object {
+        "end": Object {
+          "column": 17,
+          "line": 1,
+          "offset": 16,
+        },
+        "start": Object {
+          "column": 1,
+          "line": 1,
+          "offset": 0,
+        },
+      },
+      "type": "root",
+    },
+    "errors": Array [],
+    "examples": Array [],
+    "loc": SourceLocation {
+      "end": Position {
+        "column": 5,
+        "line": 13,
+      },
+      "start": Position {
+        "column": 2,
+        "line": 11,
+      },
+    },
+    "members": Object {
+      "events": Array [],
+      "global": Array [],
+      "inner": Array [],
+      "instance": Array [],
+      "static": Array [],
+    },
+    "name": "myNumber",
+    "namespace": "myNumber",
+    "params": Array [],
+    "path": Array [
+      Object {
+        "kind": undefined,
+        "name": "myNumber",
+      },
+    ],
+    "properties": Array [],
+    "returns": Array [],
+    "sees": Array [],
+    "tags": Array [],
+    "throws": Array [],
+    "todos": Array [],
+  },
+]
+`;
+
 exports[`config 1`] = `
 "<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
 

diff --git a/__tests__/fixture/vue.input.vue b/__tests__/fixture/vue.input.vue
@@ -0,0 +1,28 @@
+<template>
+  <div>not relevant</div>
+</template>
+
+<script>
+
+/**
+ * This Vue Component is a test
+ * @returns {vue-tested} vue-tested component
+ */
+export default {
+
+props: {
+
+  /**
+   * This is a number
+   */
+  myNumber: {
+    default: 42,
+    type: Number
+  }
+}
+}
+</script>
+
+<style>
+
+</style>
diff --git a/__tests__/test.js b/__tests__/test.js
@@ -234,3 +234,10 @@ test('.lint with bad input', async function() {
     expect(err).toBeTruthy();
   }
 });
+
+test('Vue file', async function() {
+  await pify(chdir)(__dirname);
+  const data = await documentation.build('__tests__/fixture/vue.input.vue', {});
+  normalize(data);
+  expect(data).toMatchSnapshot();
+});
diff --git a/package.json b/package.json
@@ -54,6 +54,7 @@
     "vfile-sort": "^2.1.0",
     "vinyl": "^2.1.0",
     "vinyl-fs": "^3.0.2",
+    "vue-template-compiler": "^2.5.16",
     "yargs": "^9.0.1"
   },
   "devDependencies": {

diff --git a/src/index.js b/src/index.js
@@ -1,11 +1,13 @@
 const fs = require('fs');
+const path = require('path');
 const _ = require('lodash');
 const sort = require('./sort');
 const nest = require('./nest');
 const filterAccess = require('./filter_access');
 const dependency = require('./input/dependency');
 const shallow = require('./input/shallow');
 const parseJavaScript = require('./parsers/javascript');
+const parseVueScript = require('./parsers/vue');
 const github = require('./github');
 const hierarchy = require('./hierarchy');
 const inferName = require('./infer/name');
@@ -103,6 +105,9 @@ function buildInternal(inputsAndConfig) {
       sourceFile.source = fs.readFileSync(sourceFile.file, 'utf8');
     }
 
+    if (path.extname(sourceFile.file) === '.vue') {
+      return parseVueScript(sourceFile, config).map(buildPipeline);
+    }
     return parseJavaScript(sourceFile, config).map(buildPipeline);
   }).filter(Boolean);
 

diff --git a/src/merge_config.js b/src/merge_config.js
@@ -88,7 +88,8 @@ function mergeConfig(config: Object): Promise<DocumentationConfig> {
     'js',
     'jsx',
     'es5',
-    'es6'
+    'es6',
+    'vue'
   ]);
 
   return mergeConfigFile(config).then(mergePackage);

diff --git a/src/parsers/vue.js b/src/parsers/vue.js
@@ -0,0 +1,19 @@
+/* @flow */
+
+const parseJavaScript = require('./javascript');
+const vuecompiler = require('vue-template-compiler');
+
+/**
+ * Receives a module-dep item,
+ * reads the file, parses the VueScript, and parses the JSDoc.
+ *
+ * @param {Object} data a chunk of data provided by module-deps
+ * @param {Object} config config
+ * @returns {Array<Object>} an array of parsed comments
+ */
+function parseVueScript(data: Object, config: DocumentationConfig) {
+  data.source = vuecompiler.parseComponent(data.source).script.content;
+  return parseJavaScript(data, config);
+}
+
+module.exports = parseVueScript;