Additional Parser Functionality (#84)

* Add data, watch documentation features * Add auto-type detecting column for data, computed from store column for computer * Use babel types function for node type checking * Fix data documentation to also work when data is method * Revert "Fix data documentation to also work when data is method" This reverts commit 53c3b7e. * Fix data documentation to also work when data is method * Add type columns for computed and watch * Add support for data defined with an arrow function * Add store detection for computed arrow function * Add unit tests, remove argumentsDesc from ComputedResult * Add type checking for normal JS function * Refractor ObjectMethod data check to processData * Add local running documentation * Add example for documenting component * Update vue-template-loader library to fix template root comment issues * tslint fixes, examples folder added * readme additions of samples and developer workflows
vuese · Jun 23, 2019 · 3a2eb78 · 3a2eb78
1 parent 68df228
commit 3a2eb78
Show file tree

Hide file tree

Showing 18 changed files with 845 additions and 21 deletions.
diff --git a/README.md b/README.md
@@ -46,19 +46,19 @@ Visit the following 👇 link to intuitively feel `@vuese/parser`:
 [![](https://img.shields.io/npm/v/@vuese/markdown-render.svg)](https://www.npmjs.com/package/@vuese/markdown-render)
 [![](https://img.shields.io/npm/dm/@vuese/markdown-render.svg)](https://www.npmjs.com/package/@vuese/markdown-render)
 
-[@vuese/markdown-render](http://vuese.org/markdown-render/) receives the result of the Vue file parsed by [@vuese/parser](http://vuese.org/parser/) as a parameter,  generate a `markdown` string. [@vuese/markdown-render](http://vuese.org/markdown-render/) is also used for [@vuese/cli](http://vuese.org/cli/)'s document generation, in other words, you can use [@vuese/markdown-render](http://vuese.org/markdown-render/) and [@vuese/parser](http://vuese.org/parser/) alone to write your own `CLI` tool to do something interesting.
+[@vuese/markdown-render](http://vuese.org/markdown-render/) receives the result of the Vue file parsed by [@vuese/parser](http://vuese.org/parser/) as a parameter, generate a `markdown` string. [@vuese/markdown-render](http://vuese.org/markdown-render/) is also used for [@vuese/cli](http://vuese.org/cli/)'s document generation, in other words, you can use [@vuese/markdown-render](http://vuese.org/markdown-render/) and [@vuese/parser](http://vuese.org/parser/) alone to write your own `CLI` tool to do something interesting.
 
 ## @vuese/loader
 
 `@vuese/cli` is a tool for quickly creating document prototypes that don't have a more flexible documentation solution. So this is why `@vuese/loader` and `@vuese/webpack-plugin` are needed.
 
 Our goal is to focus only on the parts that can be automated, and does not limit how your document project is organized and what document framework is used. Of course, we can also provide fast solutions.
 
-[WIP] [TODO]
+[WIP][todo]
 
 ## @vuese/webpack-plugin
 
-[WIP] [TODO]
+[WIP][todo]
 
 ## Roadmap
 
@@ -72,6 +72,49 @@ Planning for vuese2.x: [Read our roadmap](https://github.com/vuese/roadmap)
 4. Push to the branch: `git push origin my-new-feature`
 5. Submit a pull request :D
 
+Instructions on how to run the library locally can be found [here](./LOCAL_RUN.md)
+
+### Developer Resources
+
+<details><summary>Running a Local Build</summary>
+<p>
+
+In root directory of your Vuese project:
+
+1. Run `yarn run build`
+2. Run `yarn link`
+
+In project that you want to use the libaries:
+
+1. If `@vuese/cli` is not yet installed, add it: `yarn add @vuese/cli`
+2. Run `yarn link vuese-monorepo`
+3. Navigate to `node_modules/.bin` and open `vuese.cmd` and `vuese`
+4. Change any instance of `@vuese` to `vuese-monorepo\packages` in both files
+
+To generate the documentation locally, run the vuese binary from `node_modules/.bin` :
+
+1. Run `node_modules\.bin\vuese gen` (cmd)
+   or
+1. Run `node_modules/.bin/vuese gen` (powershell)
+
+</p>
+</details>
+
+<details><summary>Samples</summary>
+<p>
+
+#### Component Notation
+
+1. [Samples/Components Folder](/samples/components)
+2. [Vuese Explorer](https://vuese.github.io/vuese-explorer/)
+
+#### Component Documentation
+
+1. [Samples/Docs Folder](/samples/docs)
+
+</p>
+</details>
+
 Get started immediately in a free online dev environment:
 
 [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/vuese/vuese)
@@ -84,6 +127,7 @@ Thanks goes to these wonderful people:
 <!-- prettier-ignore -->
 | [<img src="https://avatars2.githubusercontent.com/u/14146560?v=4" width="100px;"/><br /><sub><b>HcySunYang</b></sub>](http://hcysun.me/homepage)<br />[💻](https://github.com/HcySunYang/vuese/commits?author=HcySunYang "Code") [⚠️](https://github.com/HcySunYang/vuese/commits?author=HcySunYang "Tests") [📖](https://github.com/HcySunYang/vuese/commits?author=HcySunYang "Documentation") [💡](#example-HcySunYang "Examples") | [<img src="https://avatars1.githubusercontent.com/u/5592465?v=4" width="100px;"/><br /><sub><b>Barthélémy Ledoux</b></sub>](https://github.com/elevatebart)<br />[🐛](https://github.com/HcySunYang/vuese/issues?q=author%3Aelevatebart "Bug reports") [💻](https://github.com/HcySunYang/vuese/commits?author=elevatebart "Code") | [<img src="https://avatars1.githubusercontent.com/u/17594215?v=4" width="100px;"/><br /><sub><b>Bernhard Wittmann</b></sub>](http://bernhardwittmann.com)<br />[💻](https://github.com/HcySunYang/vuese/commits?author=BerniWittmann "Code") [🤔](#ideas-BerniWittmann "Ideas, Planning, & Feedback") | [<img src="https://avatars2.githubusercontent.com/u/11501493?v=4" width="100px;"/><br /><sub><b>Steve Young</b></sub>](https://buptsteve.github.io)<br />[🐛](https://github.com/HcySunYang/vuese/issues?q=author%3ABuptStEve "Bug reports") [💻](https://github.com/HcySunYang/vuese/commits?author=BuptStEve "Code") | [<img src="https://avatars3.githubusercontent.com/u/15170275?v=4" width="100px;"/><br /><sub><b>wulunyi</b></sub>](https://github.com/wulunyi)<br />[💻](https://github.com/HcySunYang/vuese/commits?author=wulunyi "Code") | [<img src="https://avatars2.githubusercontent.com/u/5432828?v=4" width="100px;"/><br /><sub><b>Estelle00</b></sub>](https://github.com/Estelle00)<br />[💻](https://github.com/HcySunYang/vuese/commits?author=Estelle00 "Code") | [<img src="https://avatars2.githubusercontent.com/u/8364818?v=4" width="100px;"/><br /><sub><b>Matt Roxburgh</b></sub>](https://github.com/roxburghm)<br />[🐛](https://github.com/HcySunYang/vuese/issues?q=author%3Aroxburghm "Bug reports") [💻](https://github.com/HcySunYang/vuese/commits?author=roxburghm "Code") |
 | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
+
 <!-- ALL-CONTRIBUTORS-LIST:END -->
 
 ## Author

diff --git a/packages/markdown-render/__test__/__snapshots__/index.test.ts.snap b/packages/markdown-render/__test__/__snapshots__/index.test.ts.snap
@@ -16,13 +16,21 @@ exports[`Empty Components (without slots,methods,props,events) can be forced to
 
 exports[`Proper rendering of the table header 1`] = `
 Object {
+  "data": "|Name|Type|Description|Default|
+|---|---|---|---|
+|someVariable|\`String\`|Does something|-|
+",
   "events": "|Event Name|Description|Parameters|
 |---|---|---|
 |click|Triggered when clicked|a boolean value|
 ",
   "methods": "|Method|Description|Parameters|
 |---|---|---|
 |clear|Clear form|a boolean value|
+",
+  "mixIns": "|MixIn|
+|---|
+|MixIn|
 ",
   "props": "|Name|Description|Type|Required|Default|
 |---|---|---|---|---|
@@ -31,6 +39,10 @@ Object {
   "slots": "|Name|Description|Default Slot Content|
 |---|---|---|
 |header|Table header|\`<th>{{title}}</th>\`|
+",
+  "watch": "|Name|Description|Parameters|
+|---|---|---|
+|question|Something about a question|a string value|
 ",
 }
 `;
@@ -82,6 +94,36 @@ This is a description of the component
 <!-- @vuese:MyComponent:methods:end -->
 
 
+## MixIns
+
+<!-- @vuese:MyComponent:mixIns:start -->
+|MixIn|
+|---|
+|MixIn|
+
+<!-- @vuese:MyComponent:mixIns:end -->
+
+
+## Data
+
+<!-- @vuese:MyComponent:data:start -->
+|Name|Type|Description|Default|
+|---|---|---|---|
+|someVariable|\`String\`|Does something|-|
+
+<!-- @vuese:MyComponent:data:end -->
+
+
+## Watch
+
+<!-- @vuese:MyComponent:watch:start -->
+|Name|Description|Parameters|
+|---|---|---|
+|question|Something about a question|a string value|
+
+<!-- @vuese:MyComponent:watch:end -->
+
+
 ",
   "groupName": "My Group",
 }

diff --git a/packages/markdown-render/__test__/index.test.ts b/packages/markdown-render/__test__/index.test.ts
@@ -51,6 +51,26 @@ test('Proper rendering of the table header', () => {
         describe: ['Clear form'],
         argumentsDesc: ['a boolean value']
       }
+    ],
+    mixIns: [
+      {
+        mixIn: 'MixIn'
+      }
+    ],
+    data: [
+      {
+        name: 'someVariable',
+        type: 'String',
+        describe: ['Does something'],
+        default: ''
+      }
+    ],
+    watch: [
+      {
+        name: 'question',
+        describe: ['Something about a question'],
+        argumentsDesc: ['a string value']
+      }
     ]
   }
   const render = new Render(res)

diff --git a/packages/markdown-render/lib/genMarkdownTpl.ts b/packages/markdown-render/lib/genMarkdownTpl.ts
@@ -16,6 +16,8 @@ export default function(parserRes: ParserResult) {
   templateStr += parserRes.methods ? genBaseTemplate('methods') : ''
   templateStr += parserRes.computed ? genBaseTemplate('computed') : ''
   templateStr += parserRes.mixIns ? genBaseTemplate('mixIns') : ''
+  templateStr += parserRes.data ? genBaseTemplate('data') : ''
+  templateStr += parserRes.watch ? genBaseTemplate('watch') : ''
 
   return !forceGenerate && original === templateStr ? '' : templateStr
 }

diff --git a/packages/markdown-render/lib/index.ts b/packages/markdown-render/lib/index.ts
@@ -4,8 +4,10 @@ import {
   PropsResult,
   SlotResult,
   EventResult,
+  DataResult,
   MethodResult,
-  ComputedResult
+  ComputedResult,
+  WatchResult
 } from '@vuese/parser'
 import renderMarkdown, { MarkdownResult } from './renderMarkdown'
 
@@ -18,6 +20,8 @@ interface RenderOptions {
   methods: string[]
   computed: string[]
   mixIns: string[]
+  data: string[]
+  watch: string[]
 }
 
 export interface RenderResult {
@@ -27,6 +31,8 @@ export interface RenderResult {
   methods?: string
   computed?: string
   mixIns?: string
+  data?: string
+  watch?: string
 }
 
 export class Render {
@@ -41,8 +47,10 @@ export class Render {
         events: ['Event Name', 'Description', 'Parameters'],
         slots: ['Name', 'Description', 'Default Slot Content'],
         methods: ['Method', 'Description', 'Parameters'],
-        computed: ['Computed', 'Description'],
-        mixIns: ['MixIn']
+        computed: ['Computed', 'Type', 'Description', 'From Store'],
+        mixIns: ['MixIn'],
+        data: ['Name', 'Type', 'Description', 'Default'],
+        watch: ['Name', 'Description', 'Parameters']
       },
       this.options
     )
@@ -55,7 +63,9 @@ export class Render {
       events,
       methods,
       mixIns,
-      computed
+      data,
+      computed,
+      watch
     } = this.parserResult
     let md: RenderResult = {}
     if (props) {
@@ -76,6 +86,12 @@ export class Render {
     if (mixIns) {
       md.mixIns = this.mixInRender(mixIns)
     }
+    if (data) {
+      md.data = this.dataRender(data)
+    }
+    if (watch) {
+      md.watch = this.watchRender(watch)
+    }
 
     return md
   }
@@ -253,17 +269,30 @@ export class Render {
   computedRender(computedRes: ComputedResult[]) {
     const computedConfig = (this.options as RenderOptions).computed
     let code = this.renderTabelHeader(computedConfig)
-    computedRes.forEach((method: MethodResult) => {
+    computedRes.forEach((computed: ComputedResult) => {
       const row: string[] = []
       for (let i = 0; i < computedConfig.length; i++) {
         if (computedConfig[i] === 'Computed') {
-          row.push(method.name)
+          row.push(computed.name)
+        } else if (computedConfig[i] === 'Type') {
+          if (computed.type) {
+            row.push(`\`${computed.type.join('')}\``)
+            row.push()
+          } else {
+            row.push('-')
+          }
         } else if (computedConfig[i] === 'Description') {
-          if (method.describe) {
-            row.push(method.describe.join(''))
+          if (computed.describe) {
+            row.push(computed.describe.join(''))
           } else {
             row.push('-')
           }
+        } else if (computedConfig[i] === 'From Store') {
+          if (computed.isFromStore) {
+            row.push('Yes')
+          } else {
+            row.push('No')
+          }
         } else {
           row.push('-')
         }
@@ -292,6 +321,72 @@ export class Render {
     return code
   }
 
+  dataRender(dataRes: DataResult[]) {
+    const dataConfig = (this.options as RenderOptions).data
+    let code = this.renderTabelHeader(dataConfig)
+    dataRes.forEach((data: DataResult) => {
+      const row: string[] = []
+      for (let i = 0; i < dataConfig.length; i++) {
+        if (dataConfig[i] === 'Name') {
+          row.push(data.name)
+        } else if (dataConfig[i] === 'Description') {
+          if (data.describe) {
+            row.push(data.describe.join(''))
+          } else {
+            row.push('-')
+          }
+        } else if (dataConfig[i] === 'Type') {
+          if (data.type.length > 0) {
+            row.push(`\`${data.type}\``)
+          } else {
+            row.push('—')
+          }
+        } else if (dataConfig[i] === 'Default') {
+          if (data.default) {
+            row.push(data.default)
+          } else {
+            row.push('-')
+          }
+        } else {
+          row.push('-')
+        }
+      }
+      code += this.renderTabelRow(row)
+    })
+
+    return code
+  }
+
+  watchRender(watchRes: WatchResult[]) {
+    const watchConfig = (this.options as RenderOptions).watch
+    let code = this.renderTabelHeader(watchConfig)
+    watchRes.forEach((watch: WatchResult) => {
+      const row: string[] = []
+      for (let i = 0; i < watchConfig.length; i++) {
+        if (watchConfig[i] === 'Name') {
+          row.push(watch.name)
+        } else if (watchConfig[i] === 'Description') {
+          if (watch.describe) {
+            row.push(watch.describe.join(''))
+          } else {
+            row.push('-')
+          }
+        } else if (watchConfig[i] === 'Parameters') {
+          if (watch.argumentsDesc) {
+            row.push(watch.argumentsDesc.join(''))
+          } else {
+            row.push('-')
+          }
+        } else {
+          row.push('-')
+        }
+      }
+      code += this.renderTabelRow(row)
+    })
+
+    return code
+  }
+
   renderTabelHeader(header: string[]): string {
     const headerString = this.renderTabelRow(header)
     const splitLine = this.renderSplitLine(header.length)

diff --git a/packages/parser/__test__/__fixtures__/computed.vue b/packages/parser/__test__/__fixtures__/computed.vue
@@ -0,0 +1,29 @@
+<template>
+  <div></div>
+</template>
+
+<script>
+export default {
+  computed: {
+    /**
+     * @vuese
+     * Returns filtered paths
+     * @type String
+     */
+    normalComputedValue() {
+      return "this might be a string".split('').reverse('').join('')
+    },
+    /**
+     * @vuese
+     * Returns filtered paths
+     * @type Array
+     */
+    storeValue() {
+      return this.$store.state.pathsFiltered;
+    },
+    undocumentedComputed() {
+      return true
+    }
+  }
+}
+</script>